@mantyx/sdk 0.2.0 → 0.4.0

package/dist/client-ChxfhYBJ.d.cts

@@ -0,0 +1,658 @@
+import { z } from 'zod';
+
+/**
+ * Public tool helpers for the MANTYX SDK.
+ *
+ * Server-resolved (executed by MANTYX):
+ *   mantyxTool(id)            → existing workspace `Tool` row by id
+ *   mantyxPluginTool(name)    → built-in plugin tool by `@plugin/tool` name
+ *   mantyxA2A({...})          → remote Agent2Agent peer, dialed by MANTYX
+ *   mantyxMcp({...})          → remote MCP server (Streamable HTTP), proxied by MANTYX
+ *
+ * Client-resolved (executed in this process; the SDK shuttles inputs and
+ * outputs over the agent loop):
+ *   defineLocalTool({...})    → generic local tool with a Zod parameter schema
+ *   defineLocalA2A({...})     → A2A peer the SDK can reach but MANTYX cannot —
+ *                                pass an `agentCardUrl`; the SDK fetches the
+ *                                Agent Card and speaks A2A `message/send` for you.
+ *   defineLocalMcp({...})     → MCP server the SDK manages — pass either a
+ *                                Streamable HTTP `url` or a stdio
+ *                                `command`; the SDK runs `Initialize` +
+ *                                `tools/list` and forwards `tools/call` for you.
+ *
+ * The server emits a `local_tool_call` event for every client-resolved
+ * invocation. The event carries a `kind` discriminator (`"local"` is implied
+ * when omitted, `"a2a_local"` and `"mcp_local"` are explicit) so the SDK can
+ * dispatch to the right handler.
+ */
+
+type ZodLikeObject = z.ZodType<Record<string, unknown>> & {
+    _def?: unknown;
+    parse?: (value: unknown) => unknown;
+};
+/**
+ * Provider-thinking knob, mapped server-side onto each LLM's native dial:
+ * `reasoning.effort` (OpenAI), `thinkingConfig.thinkingLevel` / `thinkingBudget`
+ * (Gemini), or extended-thinking budget (Anthropic / Bedrock-Anthropic).
+ *
+ * Pass either a string anchor (`"off" | "low" | "medium" | "high"`) or an
+ * integer in `0..100` (where `0` explicitly disables provider thinking).
+ */
+type ReasoningLevel = "off" | "low" | "medium" | "high" | number;
+interface LocalTool<TArgs = Record<string, unknown>> {
+    readonly kind: "local";
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: ZodLikeObject | undefined;
+    readonly execute: (args: TArgs) => Promise<string> | string;
+}
+interface DefineLocalToolOptions<T extends ZodLikeObject | undefined> {
+    /** Lowercase alphanumeric + underscore, max 64 chars. */
+    name: string;
+    description?: string;
+    parameters?: T;
+    execute: (args: T extends ZodLikeObject ? z.infer<T> : Record<string, unknown>) => Promise<string> | string;
+}
+declare function defineLocalTool<T extends ZodLikeObject | undefined>(opts: DefineLocalToolOptions<T>): LocalTool;
+interface MantyxToolRef {
+    readonly kind: "mantyx";
+    readonly id: string;
+}
+interface MantyxPluginToolRef {
+    readonly kind: "mantyx_plugin";
+    readonly name: string;
+}
+declare function mantyxTool(id: string): MantyxToolRef;
+declare function mantyxPluginTool(name: string): MantyxPluginToolRef;
+/**
+ * Reference to a remote Agent2Agent peer reachable from MANTYX (server-resolved).
+ * MANTYX dials `agentCardUrl` over A2A's `message/send` RPC and forwards the
+ * remote agent's reply as the tool result.
+ */
+interface A2AToolRef {
+    readonly kind: "a2a";
+    readonly name: string;
+    readonly description?: string;
+    readonly agentCardUrl: string;
+    readonly headers?: Record<string, string>;
+    readonly contextId?: string;
+}
+interface MantyxA2AOptions {
+    /** Tool name surfaced to the model; must match `^[a-zA-Z0-9_]{1,64}$`. */
+    name: string;
+    description?: string;
+    /** Remote Agent Card URL (`/.well-known/agent-card.json`) or JSON-RPC root. */
+    agentCardUrl: string;
+    /** Per-request HTTP headers (typically `Authorization`). */
+    headers?: Record<string, string>;
+    /** Optional A2A `contextId` to thread multiple delegations. */
+    contextId?: string;
+}
+declare function mantyxA2A(opts: MantyxA2AOptions): A2AToolRef;
+/**
+ * Local A2A peer — the SDK fetches the Agent Card from `agentCardUrl` on
+ * the first run, ships the resolved card with the spec, and speaks A2A
+ * `message/send` to `agentCard.url` whenever MANTYX emits a
+ * `local_tool_call` for this tool. You only supply the URL.
+ *
+ * The model addresses this tool by `name` and always passes
+ * `{ message: string }` as arguments.
+ *
+ * Resolution is lazy: the card is fetched on the first `runAgent` /
+ * `streamAgent` / `createSession` (or `session.send`) call and cached on
+ * the tool ref for the rest of the process lifetime. Re-construct the ref
+ * to force a refetch.
+ */
+interface LocalA2ATool {
+    readonly kind: "a2a_local";
+    readonly name: string;
+    /** Where the SDK fetches the Agent Card from. Cached after the first hit. */
+    readonly agentCardUrl: string;
+    /**
+     * Headers used for **both** the card fetch and every `message/send` POST
+     * (typically `Authorization` for intranet peers).
+     */
+    readonly headers: Record<string, string> | undefined;
+    /**
+     * Internal cache of the resolved Agent Card. Populated lazily by the
+     * client on the first run; not part of the user contract.
+     * @internal
+     */
+    _resolvedCard?: ResolvedAgentCard;
+}
+/** Internal: the snapshot of a resolved A2A Agent Card. */
+interface ResolvedAgentCard {
+    /** Required by the A2A spec; used for the synthesized tool description. */
+    readonly name: string;
+    /** Peer's A2A endpoint — where the SDK POSTs `message/send`. */
+    readonly url?: string;
+    /** Anything else the peer publishes; forwarded verbatim onto the wire. */
+    readonly [k: string]: unknown;
+}
+interface DefineLocalA2AOptions {
+    /** Tool name surfaced to the model. Must match `^[a-zA-Z0-9_]{1,64}$`. */
+    name: string;
+    /**
+     * URL of the peer's Agent Card (`/.well-known/agent-card.json` is the
+     * conventional path). The SDK fetches this on the first run, parses it,
+     * and ships the resolved card with the spec. The resolved card's `url`
+     * field is then used as the `message/send` target.
+     */
+    agentCardUrl: string;
+    /**
+     * Headers attached to **both** the card fetch and every `message/send`
+     * POST (typically `Authorization` for intranet peers).
+     */
+    headers?: Record<string, string>;
+}
+declare function defineLocalA2A(opts: DefineLocalA2AOptions): LocalA2ATool;
+/**
+ * Reference to a remote MCP server (Streamable HTTP) discovered + proxied by
+ * MANTYX. Each tool in the catalog is exposed to the model as `<name>_<tool>`.
+ */
+interface McpToolRef {
+    readonly kind: "mcp";
+    readonly name: string;
+    readonly url: string;
+    readonly headers?: Record<string, string>;
+    readonly toolFilter?: string[];
+}
+interface MantyxMcpOptions {
+    /** Server label; used to prefix every discovered tool. */
+    name: string;
+    /** Streamable HTTP MCP endpoint. */
+    url: string;
+    headers?: Record<string, string>;
+    /** Optional allowlist of MCP tool names. */
+    toolFilter?: string[];
+}
+declare function mantyxMcp(opts: MantyxMcpOptions): McpToolRef;
+/**
+ * Streamable HTTP transport spec for {@link defineLocalMcp}.
+ */
+interface LocalMcpHttpTransport {
+    /** Streamable HTTP MCP endpoint (e.g. `http://localhost:8080/mcp`). */
+    url: string;
+    /** HTTP headers sent on every MCP request (typically `Authorization`). */
+    headers?: Record<string, string>;
+}
+/**
+ * stdio transport spec for {@link defineLocalMcp}. The SDK spawns the
+ * specified executable with the given arguments and speaks JSON-RPC over
+ * its stdin/stdout streams.
+ */
+interface LocalMcpStdioTransport {
+    /** Executable to launch (e.g. `mcp-server-filesystem`, `node`, `uvx`). */
+    command: string;
+    /** Arguments passed verbatim. */
+    args?: string[];
+    /** Environment variables for the child process. Inherited if undefined. */
+    env?: Record<string, string>;
+    /** Working directory for the child process. */
+    cwd?: string;
+}
+/**
+ * Local MCP server — the SDK manages the entire MCP lifecycle for you.
+ *
+ * Pass either a Streamable HTTP `url` or an stdio `command` (mutually
+ * exclusive). On the first run, the SDK opens the transport, runs MCP's
+ * `Initialize` (capturing the `Implementation` block) and `tools/list`
+ * (capturing the catalog), and ships both inline as part of the spec. On
+ * every `local_tool_call` with `kind: "mcp_local"` the SDK forwards the
+ * call to MCP `tools/call` on the cached connection and POSTs the
+ * flattened text response back to MANTYX.
+ *
+ * Connections are reused across runs and across messages within a session
+ * and closed on `runAgent` completion / `session.end()`.
+ */
+interface LocalMcpServer {
+    readonly kind: "mcp_local";
+    readonly name: string;
+    /** One-of with {@link stdio} — the transport spec is mutually exclusive. */
+    readonly http: LocalMcpHttpTransport | undefined;
+    /** One-of with {@link http} — the transport spec is mutually exclusive. */
+    readonly stdio: LocalMcpStdioTransport | undefined;
+    /**
+     * Internal cache of the resolved MCP client + catalog. Populated lazily
+     * by the run driver on the first run; not part of the user contract.
+     * @internal
+     */
+    _resolved?: ResolvedMcpServer;
+}
+/**
+ * Internal: the live MCP client + the snapshot the SDK ships on the wire.
+ */
+interface ResolvedMcpServer {
+    /** The MCP `Implementation` block from `Initialize`. */
+    readonly serverInfo: {
+        name: string;
+        version?: string;
+        [k: string]: unknown;
+    };
+    /** Verbatim `tools/list` output. */
+    readonly tools: ReadonlyArray<{
+        readonly name: string;
+        readonly description?: string;
+        readonly inputSchema: Record<string, unknown>;
+        readonly annotations?: Record<string, unknown>;
+        readonly [k: string]: unknown;
+    }>;
+    /**
+     * The live MCP client. Used by the run driver to call `tools/call`. The
+     * concrete type depends on the transport — kept loose so this header
+     * file doesn't have to import the MCP SDK type.
+     */
+    readonly client: McpClientLike;
+    /** Closes the MCP transport (idempotent). */
+    readonly close: () => Promise<void>;
+}
+/** Minimal interface this SDK uses against an MCP client. */
+interface McpClientLike {
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<{
+        content?: Array<{
+            type: string;
+            text?: string;
+            [k: string]: unknown;
+        }>;
+        isError?: boolean;
+        [k: string]: unknown;
+    }>;
+}
+interface DefineLocalMcpOptions {
+    /**
+     * Server label echoed back as `mcpServer` on every `local_tool_call`. The
+     * SDK auto-prefixes each discovered tool's wire-level `name` with
+     * `<this>_` so the model sees a non-colliding `<server>_<tool>` surface
+     * — mirroring how MANTYX prefixes for `kind: "mcp"`.
+     */
+    name: string;
+    /**
+     * Streamable HTTP transport. Mutually exclusive with {@link command}.
+     */
+    url?: string;
+    /**
+     * Headers attached to every MCP request when using the HTTP transport.
+     */
+    headers?: Record<string, string>;
+    /**
+     * stdio transport: executable to launch. Mutually exclusive with
+     * {@link url}.
+     */
+    command?: string;
+    /** Arguments for the stdio child process. */
+    args?: string[];
+    /** Environment variables for the stdio child process. */
+    env?: Record<string, string>;
+    /** Working directory for the stdio child process. */
+    cwd?: string;
+}
+declare function defineLocalMcp(opts: DefineLocalMcpOptions): LocalMcpServer;
+type ToolRef = MantyxToolRef | MantyxPluginToolRef | LocalTool | A2AToolRef | LocalA2ATool | McpToolRef | LocalMcpServer;
+declare function isLocalTool(t: ToolRef): t is LocalTool;
+declare function isLocalA2ATool(t: ToolRef): t is LocalA2ATool;
+declare function isLocalMcpServer(t: ToolRef): t is LocalMcpServer;
+
+declare const DEFAULT_BASE_URL = "https://app.mantyx.io";
+interface MantyxClientOptions {
+    apiKey: string;
+    workspaceSlug: string;
+    /** Defaults to `https://app.mantyx.io`. Override for self-hosted instances. */
+    baseUrl?: string;
+    /** Optional `fetch` override (e.g. node-fetch wrapper, or a custom HTTP client). */
+    fetch?: typeof fetch;
+    /** Default per-request timeout in milliseconds. Default: 60s. */
+    timeoutMs?: number;
+}
+interface ModelInfo {
+    id: string;
+    label: string;
+    provider: string;
+    vendorModelId: string;
+    source: "workspace_provider" | "platform_offering";
+    contextWindowTokens: number | null;
+    pricing: {
+        inputPer1MUsd: number | null;
+        outputPer1MUsd: number | null;
+        cacheReadPer1MUsd: number | null;
+    } | null;
+}
+interface ModelCatalog {
+    models: ModelInfo[];
+    defaultModelId: string | null;
+}
+interface AgentSpecBase {
+    name?: string;
+    /**
+     * Reference to a persisted MANTYX agent in this workspace. When set, the
+     * server hydrates `systemPrompt`, `modelId`, and the agent's own tools
+     * (memory, skills, plugin tools, …) from the Agent row at run time, and any
+     * `tools` you supply here are merged on top — typically `local` tools the
+     * SDK wants the agent to be able to call back into.
+     *
+     * Either `agentId` or `systemPrompt` must be set.
+     */
+    agentId?: string;
+    /** Required unless `agentId` is set. */
+    systemPrompt?: string;
+    modelId?: string;
+    tools?: ToolRef[];
+    /**
+     * Provider thinking strength: a string anchor (`"off" | "low" | "medium" |
+     * "high"`) or an integer in `0..100` (where `0` explicitly disables provider
+     * thinking on reasoning models). The server maps this onto each LLM's
+     * native dial — see `docs/agent-runs-protocol.md` §4.4.
+     *
+     * For session-scoped runs the session value sets the default; per-message
+     * overrides on `session.send` apply to that single run.
+     */
+    reasoningLevel?: ReasoningLevel;
+    budgets?: {
+        maxToolTurns?: number;
+    };
+    /**
+     * Constrains the model's **final assistant text** to a JSON document
+     * matching a JSON Schema. The terminal `result` event still carries the
+     * reply as `text: string`, but that string is guaranteed-parseable JSON.
+     *
+     * `name` (optional) is a stable identifier the server forwards to the
+     * provider (OpenAI `text.format.name`, Anthropic synthetic-tool name).
+     * Defaults to `"output"`. Must match `/^[a-zA-Z0-9_-]{1,64}$/`.
+     *
+     * `schema` is a JSON Schema describing the final assistant text. Its
+     * root must be a JSON **object** — most providers reject array / scalar
+     * roots in structured-output mode. The schema is shipped verbatim;
+     * MANTYX does not validate its contents (the provider does).
+     *
+     * Use {@link parseRunOutput} on the resulting `RunResult` to JSON.parse
+     * the reply (and optionally re-validate against your own zod / typebox /
+     * ajv schema). See `docs/wire-protocol.md` §7.
+     */
+    outputSchema?: OutputSchema;
+    /**
+     * Flat string→string KV carried alongside the run / session for
+     * observability. Use it to tag runs with your own application identifiers
+     * (customer id, environment, workflow name, …) — the values are visible in
+     * the MANTYX dashboard and can be filtered there.
+     *
+     * Limits enforced server-side: max 16 entries; keys match
+     * `[A-Za-z0-9._-]{1,64}`; values are strings ≤ 256 chars; serialized JSON
+     * ≤ 4 KB. For session-scoped runs, the session's metadata is inherited and
+     * any per-message override is merged on top.
+     */
+    metadata?: Record<string, string>;
+}
+interface RunSpec extends AgentSpecBase {
+    prompt?: string;
+    messages?: Array<{
+        role: "user" | "assistant" | "system";
+        content: string;
+    }>;
+    /** Receives streaming assistant text deltas. */
+    onAssistantDelta?: (delta: string) => void;
+    /** Receives raw events (assistant_message, local_tool_call, tool_result, ...) for advanced consumers. */
+    onEvent?: (event: RunEvent) => void;
+    /** Aborts the run on the client and best-effort cancels server-side. */
+    signal?: AbortSignal;
+}
+type SessionSpec = AgentSpecBase;
+/**
+ * Constrains the final assistant text to a JSON document matching a
+ * JSON Schema. See {@link AgentSpecBase.outputSchema} for the full
+ * semantics.
+ */
+interface OutputSchema {
+    /** Optional. Defaults to `"output"`. Must match `/^[a-zA-Z0-9_-]{1,64}$/`. */
+    name?: string;
+    /** Required. JSON Schema describing the final assistant text. Root must be a JSON object. */
+    schema: Record<string, unknown>;
+}
+interface RunResult {
+    runId: string;
+    text: string;
+    events: RunEvent[];
+}
+interface RunEventBase {
+    seq: number;
+    type: string;
+}
+interface AssistantDeltaEvent extends RunEventBase {
+    type: "assistant_delta";
+    text: string;
+}
+interface ThinkingDeltaEvent extends RunEventBase {
+    type: "thinking_delta";
+    text: string;
+}
+interface AssistantMessageEvent extends RunEventBase {
+    type: "assistant_message";
+    text: string;
+}
+interface ServerToolResultEvent extends RunEventBase {
+    type: "tool_result";
+    name: string;
+    args?: Record<string, unknown>;
+    ok?: boolean;
+    summary?: string;
+    phase?: "start" | "end";
+}
+interface LocalToolCallEvent extends RunEventBase {
+    type: "local_tool_call";
+    toolUseId: string;
+    /**
+     * The model-facing tool name. For `kind: "mcp_local"` events this is the
+     * `<server>_<tool>` name the SDK declared on the wire; the SDK looks up
+     * the local MCP server via `mcpServer` and forwards `mcpToolName` to
+     * `tools/call` rather than parsing the prefix itself.
+     */
+    name: string;
+    args: Record<string, unknown>;
+    /**
+     * Discriminator for which client-resolved handler should run.
+     * - `"local"` (or omitted) — generic local tool
+     * - `"a2a_local"` — local Agent2Agent peer
+     * - `"mcp_local"` — local MCP server tool
+     */
+    kind?: "local" | "a2a_local" | "mcp_local";
+    /**
+     * Present on `kind: "a2a_local"` — the full A2A Agent Card the SDK shipped
+     * with the spec, echoed back unchanged. Surfaced for advanced consumers
+     * (`onEvent` / `streamAgent` callers); the built-in dispatcher ignores it
+     * because it already has the cached card from the original
+     * `defineLocalA2A` resolution.
+     */
+    agentCard?: {
+        name: string;
+        url?: string;
+        [k: string]: unknown;
+    };
+    /** Present on `kind: "mcp_local"` — server label declared via `defineLocalMcp`. */
+    mcpServer?: string;
+    /**
+     * Present on `kind: "mcp_local"` — the model-facing tool name as declared on
+     * the wire. Always equals `name`; surfaced as a separate field for the SDK's
+     * convenience when dispatching into a local MCP client.
+     */
+    mcpToolName?: string;
+    /**
+     * Present on `kind: "mcp_local"` — the verbatim `Implementation` block from
+     * MCP `Initialize`, echoed back for observability.
+     */
+    mcpServerInfo?: {
+        name: string;
+        version?: string;
+        [k: string]: unknown;
+    };
+}
+interface LocalToolResultInEvent extends RunEventBase {
+    type: "local_tool_result_in";
+    toolUseId: string;
+    result?: string;
+    error?: string;
+}
+interface ResultEvent extends RunEventBase {
+    type: "result";
+    subtype: string;
+    text?: string;
+    error?: string;
+}
+interface ErrorEvent extends RunEventBase {
+    type: "error";
+    error: string;
+    code?: string;
+}
+interface CancelledEvent extends RunEventBase {
+    type: "cancelled";
+    reason?: string;
+}
+type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
+    type: string;
+    [key: string]: unknown;
+});
+interface SessionInfo {
+    id: string;
+    name: string;
+    status: "active" | "ended";
+    createdAt: string;
+    lastUsedAt: string;
+    endedAt: string | null;
+    agentSpec: AgentSpecBase;
+    messages: Array<{
+        role: "user" | "assistant" | "system";
+        content: string;
+    }>;
+    /** Metadata that was attached to the session at create time, returned for observability. */
+    metadata: Record<string, string>;
+}
+declare class MantyxClient {
+    readonly options: Required<Pick<MantyxClientOptions, "apiKey" | "workspaceSlug" | "baseUrl">> & {
+        fetch: typeof fetch;
+        timeoutMs: number;
+    };
+    constructor(opts: MantyxClientOptions);
+    listModels(): Promise<ModelCatalog>;
+    runAgent(spec: RunSpec): Promise<RunResult>;
+    streamAgent(spec: RunSpec): AsyncGenerator<RunEvent, void, void>;
+    /**
+     * Internal registry of client-resolved tool handlers. Exposed for callers
+     * who drive the run loop manually via `driveRun` / `streamRunEvents`.
+     */
+    collectHandlers(tools: ToolRef[]): LocalHandlers;
+    createSession(spec: SessionSpec): Promise<AgentSession>;
+    /**
+     * Re-emit a `local_tool_call` event into the right local handler. Useful
+     * for tests and for users who consume events via `streamAgent` themselves.
+     */
+    dispatchLocalToolFromEvent(runId: string, ev: LocalToolCallEvent, handlers: LocalHandlers): Promise<void>;
+    resumeSession(sessionId: string, opts?: {
+        tools?: ToolRef[];
+    }): Promise<AgentSession>;
+    endSession(sessionId: string): Promise<void>;
+    getSessionInfo(sessionId: string): Promise<SessionInfo>;
+    /** Drive an existing run to completion (collect events, dispatch local tools). */
+    driveRun(runId: string, handlers: LocalHandlers, opts?: {
+        onAssistantDelta?: (delta: string) => void;
+        onEvent?: (event: RunEvent) => void;
+        signal?: AbortSignal;
+    }): Promise<RunResult>;
+    streamRunEvents(runId: string, handlers: LocalHandlers, signal?: AbortSignal): AsyncGenerator<RunEvent, void, void>;
+    dispatchLocalTool(runId: string, ev: LocalToolCallEvent, handlers: LocalHandlers): Promise<void>;
+    postToolResult(runId: string, toolUseId: string, payload: {
+        result?: string;
+        error?: string;
+    }): Promise<void>;
+    cancelRun(runId: string): Promise<void>;
+    private absoluteUrl;
+    private authHeaders;
+    request<T>(args: {
+        method: string;
+        path: string;
+        body?: unknown;
+        timeoutMs?: number;
+    }): Promise<T>;
+    private errorFromResponse;
+}
+declare class AgentSession {
+    readonly id: string;
+    readonly client: MantyxClient;
+    private readonly handlers;
+    private readonly tools;
+    constructor(client: MantyxClient, id: string, handlers: LocalHandlers, tools?: ToolRef[]);
+    send(prompt: string, opts?: {
+        onAssistantDelta?: (s: string) => void;
+        signal?: AbortSignal;
+        /**
+         * Per-message metadata override. Server-side this is merged on top of
+         * the session's metadata at run-creation time (run-level keys win).
+         * Useful for tagging individual turns (e.g. `{ "trace_id": "abc" }`).
+         */
+        metadata?: Record<string, string>;
+        /**
+         * Per-message override for `reasoningLevel`. Applies only to this run
+         * and does not mutate the session's stored value.
+         */
+        reasoningLevel?: ReasoningLevel;
+        /**
+         * Per-message override for `outputSchema`. Applies only to this run
+         * and does not mutate the session's stored value.
+         */
+        outputSchema?: OutputSchema;
+    }): Promise<RunResult>;
+    stream(prompt: string, opts?: {
+        signal?: AbortSignal;
+        metadata?: Record<string, string>;
+        reasoningLevel?: ReasoningLevel;
+        outputSchema?: OutputSchema;
+    }): AsyncGenerator<RunEvent, void, void>;
+    private buildSessionMessageBody;
+    history(): Promise<Array<{
+        role: "user" | "assistant" | "system";
+        content: string;
+    }>>;
+    info(): Promise<SessionInfo>;
+    end(): Promise<void>;
+}
+/** Internal registry of client-resolved handlers, indexed by `kind`. */
+interface LocalHandlers {
+    /** `kind: "local"` — generic local tools, indexed by tool name. */
+    localTools: Map<string, LocalTool>;
+    /** `kind: "a2a_local"` — local A2A peers, indexed by tool name. */
+    a2aTools: Map<string, LocalA2ATool>;
+    /** `kind: "mcp_local"` — local MCP servers, indexed by server name. */
+    mcpServers: Map<string, LocalMcpServer>;
+}
+/**
+ * Parse the terminal text of a `RunResult` as JSON.
+ *
+ * When the run was submitted with `outputSchema`, MANTYX (via the LLM
+ * provider) guarantees the reply parses as JSON in the *vast* majority of
+ * cases. Transient model errors (refusal text, truncation under
+ * `max_tokens` pressure, exotic Unicode) can still produce strings that
+ * fail to `JSON.parse` in rare edge cases — this helper centralises that
+ * brittle step and surfaces a typed {@link MantyxParseError} on failure
+ * with the original text preserved on `err.text`.
+ *
+ * Pass an optional `validator` (zod's `.parse`, an Ajv compiled validator,
+ * or any function) to re-validate against your source-of-truth schema. The
+ * validator's return value (or thrown error) is forwarded to the caller.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { parseRunOutput } from "@mantyx/sdk";
+ *
+ * const Schema = z.object({ city: z.string(), temperature_c: z.number() });
+ * const result = await client.runAgent({
+ *   systemPrompt: "...",
+ *   prompt: "What's the weather in SF?",
+ *   outputSchema: { name: "weather_report", schema: weatherJsonSchema },
+ * });
+ * const report = parseRunOutput(result, Schema.parse.bind(Schema));
+ * //    ^? { city: string; temperature_c: number }
+ * ```
+ */
+declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
+
+export { type A2AToolRef as A, type RunSpec as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, type SessionInfo as F, type SessionSpec as G, type ThinkingDeltaEvent as H, defineLocalA2A as I, defineLocalMcp as J, defineLocalTool as K, type LocalA2ATool as L, MantyxClient as M, isLocalA2ATool as N, type OutputSchema as O, isLocalMcpServer as P, isLocalTool as Q, type ReasoningLevel as R, type ServerToolResultEvent as S, type ToolRef as T, mantyxA2A as U, mantyxMcp as V, mantyxPluginTool as W, mantyxTool as X, parseRunOutput as Y, type ZodLikeObject as Z, AgentSession as a, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, type DefineLocalA2AOptions as e, type DefineLocalMcpOptions as f, type DefineLocalToolOptions as g, type LocalHandlers as h, type LocalMcpHttpTransport as i, type LocalMcpServer as j, type LocalMcpStdioTransport as k, type LocalTool as l, type LocalToolCallEvent as m, type LocalToolResultInEvent as n, type MantyxA2AOptions as o, type MantyxClientOptions as p, type MantyxMcpOptions as q, type MantyxPluginToolRef as r, type MantyxToolRef as s, type McpToolRef as t, type ModelCatalog as u, type ModelInfo as v, type ResultEvent as w, type RunEvent as x, type RunEventBase as y, type RunResult as z };