@mantyx/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+import { z } from 'zod';
+
+/**
+ * Public tool helpers for the MANTYX SDK.
+ *
+ *   defineLocalTool({ name, description, parameters, execute })
+ *     → A tool that runs in the developer's process. The MANTYX server pauses
+ *       the agent loop, emits a `local_tool_call` event, and waits for the SDK
+ *       to POST the result back.
+ *
+ *   mantyxTool(id)            → Reference an existing workspace `Tool` row by id.
+ *   mantyxPluginTool(name)    → Reference a built-in plugin tool by `@plugin/tool` name.
+ */
+
+type ZodLikeObject = z.ZodType<Record<string, unknown>> & {
+    _def?: unknown;
+    parse?: (value: unknown) => unknown;
+};
+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 MantyxToolRef {
+    readonly kind: "mantyx";
+    readonly id: string;
+}
+interface MantyxPluginToolRef {
+    readonly kind: "mantyx_plugin";
+    readonly name: string;
+}
+type ToolRef = MantyxToolRef | MantyxPluginToolRef | LocalTool;
+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;
+declare function mantyxTool(id: string): MantyxToolRef;
+declare function mantyxPluginTool(name: string): MantyxPluginToolRef;
+declare function isLocalTool(t: ToolRef): t is LocalTool;
+
+declare const DEFAULT_BASE_URL = "https://api.mantyx.com";
+interface MantyxClientOptions {
+    apiKey: string;
+    workspaceSlug: string;
+    /** Defaults to `https://api.mantyx.com`. 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[];
+    budgets?: {
+        maxToolTurns?: number;
+    };
+    /**
+     * 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;
+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;
+    name: string;
+    args: Record<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>;
+    createSession(spec: SessionSpec): Promise<AgentSession>;
+    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: Map<string, LocalTool>, opts?: {
+        onAssistantDelta?: (delta: string) => void;
+        onEvent?: (event: RunEvent) => void;
+        signal?: AbortSignal;
+    }): Promise<RunResult>;
+    streamRunEvents(runId: string, handlers: Map<string, LocalTool>, signal?: AbortSignal): AsyncGenerator<RunEvent, void, void>;
+    dispatchLocalTool(runId: string, ev: LocalToolCallEvent, handlers: Map<string, LocalTool>): 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 toolsForResume;
+    constructor(client: MantyxClient, id: string, handlers: Map<string, LocalTool>, toolsForResume?: 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>;
+    }): Promise<RunResult>;
+    stream(prompt: string, opts?: {
+        signal?: AbortSignal;
+        metadata?: Record<string, string>;
+    }): AsyncGenerator<RunEvent, void, void>;
+    history(): Promise<Array<{
+        role: "user" | "assistant" | "system";
+        content: string;
+    }>>;
+    info(): Promise<SessionInfo>;
+    end(): Promise<void>;
+}
+
+/**
+ * Error types raised by the MANTYX SDK.
+ */
+declare class MantyxError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    readonly hint: string | undefined;
+    constructor(message: string, opts?: {
+        code?: string;
+        status?: number;
+        hint?: string;
+    });
+}
+declare class MantyxNetworkError extends MantyxError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+declare class MantyxAuthError extends MantyxError {
+    constructor(message?: string);
+}
+declare class MantyxToolError extends MantyxError {
+    readonly toolName: string;
+    constructor(toolName: string, message: string);
+}
+declare class MantyxRunError extends MantyxError {
+    readonly runId: string;
+    readonly subtype: string;
+    constructor(runId: string, subtype: string, message: string);
+}
+
+/**
+ * Lightweight Zod → JSON Schema converter for tool parameter definitions.
+ *
+ * Tries `z.toJSONSchema` (Zod v4+) first; falls back to a hand-rolled walker
+ * for v3 schemas so the SDK works on a wide range of zod versions.
+ *
+ * The output is a JSON-Schema-shaped object with `type: "object"`, `properties`,
+ * and `required`. The MANTYX server feeds this to LLM providers verbatim, so
+ * unsupported zod features (effects, transforms, intersections) degrade to a
+ * permissive `"object"` description rather than failing.
+ */
+
+type JsonSchema = Record<string, unknown>;
+declare function zodToJsonSchema(schema: z.ZodType<unknown>): JsonSchema;
+/**
+ * Coerce a JSON-Schema-shaped value into a wire object suitable for the
+ * MANTYX local-tool definition payload. Accepts either a Zod schema or an
+ * already-shaped JSON Schema object.
+ */
+declare function toToolParametersWire(parameters: z.ZodType<unknown> | JsonSchema | undefined): JsonSchema;
+
+/**
+ * Minimal Server-Sent Events parser.
+ *
+ * Reads a `ReadableStream<Uint8Array>` (the body of a `fetch()` response) and
+ * yields parsed events with `id`, `event` and `data` fields. We deliberately
+ * keep this dependency-free instead of pulling in `eventsource` / `eventsource-parser`
+ * so the SDK has the smallest possible install footprint.
+ *
+ * Reconnect/replay is handled at a higher layer using `Last-Event-ID` (the
+ * default for browsers' `EventSource`) plus a `?lastSeq=` query param so curl
+ * users and SSE-via-fetch consumers both work.
+ */
+interface SseEvent {
+    id?: string;
+    event?: string;
+    data: string;
+}
+interface SseStreamOptions {
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Async generator yielding parsed SSE events from a fetch response body.
+ * Comment frames (`:keep-alive`) are dropped.
+ */
+declare function readSseStream(body: ReadableStream<Uint8Array> | null, opts?: SseStreamOptions): AsyncGenerator<SseEvent, void, void>;
+
+/**
+ * Release version — synced from repo root VERSION (`npm run sync-version`).
+ */
+declare const SDK_VERSION = "0.1.0";
+
+export { AgentSession, type AgentSpecBase, type AssistantDeltaEvent, type AssistantMessageEvent, type CancelledEvent, DEFAULT_BASE_URL, type DefineLocalToolOptions, type ErrorEvent, type LocalTool, type LocalToolCallEvent, type LocalToolResultInEvent, MantyxAuthError, MantyxClient, type MantyxClientOptions, MantyxError, MantyxNetworkError, type MantyxPluginToolRef, MantyxRunError, MantyxToolError, type MantyxToolRef, type ModelCatalog, type ModelInfo, type ResultEvent, type RunEvent, type RunEventBase, type RunResult, type RunSpec, SDK_VERSION, type ServerToolResultEvent, type SessionInfo, type SessionSpec, type SseEvent, type SseStreamOptions, type ThinkingDeltaEvent, type ToolRef, type ZodLikeObject, defineLocalTool, isLocalTool, mantyxPluginTool, mantyxTool, readSseStream, toToolParametersWire, zodToJsonSchema };