@mantyx/sdk 0.9.1 → 0.10.1

package/dist/{client-BB6cjfsz.d.cts → client-CZUVldDx.d.cts}

@@ -1,5 +1,306 @@
 import { z } from 'zod';
 
+/**
+ * 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);
+}
+/**
+ * Raised on `403 insufficient_scope`, returned when an OAuth access token
+ * is missing one of the scopes a route demands (see
+ * `docs/agent-runs-protocol.md` §2.2 for the per-endpoint table).
+ *
+ * `requiredScopes` carries the verbatim `required` value from the
+ * server's response — a single scope for most routes, an array when the
+ * route demands more than one. The SDK is expected to surface this so
+ * callers can drive a re-consent flow (e.g. "please re-authorise the
+ * app with `sessions:write` enabled").
+ *
+ * Workspace API keys never trip this error — they carry no granular
+ * scopes. It is OAuth-only.
+ */
+declare class MantyxScopeError extends MantyxError {
+    /**
+     * Scope(s) the route demanded. Always at least one entry; usually
+     * exactly one. New routes may demand more scopes in the future.
+     */
+    readonly requiredScopes: readonly string[];
+    constructor(message: string, requiredScopes: readonly string[]);
+}
+declare class MantyxToolError extends MantyxError {
+    readonly toolName: string;
+    constructor(toolName: string, message: string);
+}
+/**
+ * Optional triage attributes the runner attaches to terminal `error`
+ * events. Mirrors the wire fields described in
+ * `docs/agent-runs-protocol.md` §7 ("error event payload fields") so SDK
+ * callers can render structured UI status notes ("model truncated — JSON
+ * likely incomplete") and drive retry policy without re-parsing the
+ * human-readable `message`.
+ */
+interface MantyxRunErrorInit {
+    /**
+     * Canonical category of failure. One of `"rate_limit"`, `"overloaded"`,
+     * `"server"`, `"context_window"`, `"truncation"`, `"invalid_request"`,
+     * `"auth"`, `"timeout"`, `"local_timeout"`, `"upstream_deadline"`,
+     * `"unknown"`. New categories may land additively — callers should
+     * default-branch to `"unknown"` for unrecognized values.
+     */
+    errorClass?: string;
+    /**
+     * Canonical lowercase stop reason normalized across providers
+     * (`"max_tokens"`, `"refusal"`, `"malformed_function_call"`, …). When
+     * present, mirrors the value carried on the last `assistant_message`
+     * event preceding the failure.
+     */
+    finishReason?: string | null;
+    /**
+     * **Best-effort raw bytes** the model emitted before the failure. For
+     * `outputSchema` runs this is likely **incomplete JSON** that will
+     * fail `JSON.parse` — treat it as diagnostic data, never as a
+     * schema-conformant reply.
+     */
+    partialText?: string;
+    /**
+     * Coarse retry hint inherited from the pipeline's error classifier.
+     * Informational; the SDK still owns the actual retry decision.
+     */
+    retryable?: boolean;
+}
+declare class MantyxRunError extends MantyxError {
+    readonly runId: string;
+    readonly subtype: string;
+    /** See {@link MantyxRunErrorInit.errorClass}. */
+    readonly errorClass: string | undefined;
+    /** See {@link MantyxRunErrorInit.finishReason}. */
+    readonly finishReason: string | null | undefined;
+    /** See {@link MantyxRunErrorInit.partialText}. */
+    readonly partialText: string | undefined;
+    /** See {@link MantyxRunErrorInit.retryable}. */
+    readonly retryable: boolean | undefined;
+    constructor(runId: string, subtype: string, message: string, init?: MantyxRunErrorInit);
+}
+/**
+ * Thrown by {@link parseRunOutput} when the run's terminal text was supposed
+ * to be a JSON document (because `outputSchema` was set on the spec) but
+ * either failed to JSON.parse or failed the user-supplied validator.
+ *
+ * The original `text` is preserved on the `text` field so callers can log
+ * the raw model output for debugging.
+ */
+declare class MantyxParseError extends MantyxError {
+    readonly text: string;
+    constructor(message: string, text: string, opts?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * MANTYX OAuth 2.0 refresh client: trade a stored refresh token for
+ * short-lived access tokens, revoke tokens at sign-out, and expose
+ * a {@link TokenSource} the {@link MantyxClient} HTTP layer calls
+ * before every request (and again on 401).
+ *
+ * The library is intentionally **refresh-only**. It assumes the caller
+ * already obtained the refresh token through their own sign-in flow
+ * (Authorization Code + PKCE in a browser, native redirect, server-
+ * side exchange — whatever fits the host application). The SDK does
+ * not drive consent, does not initiate auth-code exchanges, and does
+ * not bundle PKCE helpers.
+ *
+ * Wire contract (`docs/oauth.md`):
+ *
+ * - Token endpoint: `POST <baseUrl>/api/oauth/token`, form-encoded,
+ *   `grant_type=refresh_token`. Echoes back the same `refresh_token`
+ *   the client sent (refresh tokens are persistent and non-rotating).
+ * - Revoke endpoint: `POST <baseUrl>/api/oauth/revoke`, form-encoded.
+ * - Access tokens (`mantyx_at_…`) live 1 hour (`expires_in: 3600`).
+ * - Refresh tokens (`mantyx_rt_…`) are long-lived; the caller persists
+ *   them once at first sign-in (encrypted at rest) and the SDK re-mints
+ *   access tokens from the same value on demand.
+ */
+
+declare const DEFAULT_OAUTH_BASE_URL = "https://app.mantyx.io";
+/** Skew (ms) before `expiresAt` at which a TokenSource will pre-emptively refresh. Default 60s. */
+declare const DEFAULT_REFRESH_SKEW_MS = 60000;
+/**
+ * Raised on a non-2xx response from `POST /api/oauth/token` or
+ * `POST /api/oauth/revoke`. Carries the RFC 6749 `error` discriminator
+ * (`"invalid_grant"`, `"invalid_client"`, `"unsupported_grant_type"`,
+ * …) and the optional `error_description` so callers can branch on
+ * machine-readable values without parsing the human message.
+ *
+ * `invalid_grant` from the refresh path specifically signals that the
+ * refresh token has been revoked (or the OAuth grant / application
+ * was deleted). The SDK never loops on this — callers should route
+ * the user back to a fresh sign-in.
+ */
+declare class MantyxOAuthError extends MantyxError {
+    readonly oauthError: string;
+    readonly oauthErrorDescription: string | undefined;
+    constructor(oauthError: string, oauthErrorDescription: string | undefined, status: number);
+}
+/**
+ * Decoded `POST /api/oauth/token` response, augmented with an absolute
+ * `expiresAt` timestamp the SDK uses to decide when to refresh.
+ *
+ * On the refresh grant the response's `refreshToken` is identical to
+ * the value the client just sent (refresh tokens never rotate). The
+ * field is surfaced for symmetry with whatever the calling app's
+ * sign-in flow already does.
+ */
+interface OAuthToken {
+    readonly accessToken: string;
+    readonly refreshToken: string | undefined;
+    readonly tokenType: string;
+    readonly expiresIn: number;
+    /** Absolute Unix-ms timestamp set when the SDK parsed the response. */
+    readonly expiresAt: number;
+    readonly scope: string | undefined;
+}
+/** Why the SDK asked the {@link TokenSource} for the current access token. */
+type TokenRequestReason = "initial" | "expired" | "unauthorized";
+/**
+ * A `TokenSource` produces the current access token on demand. The
+ * {@link MantyxClient} HTTP layer calls it before every request. When
+ * called with `reason: "unauthorized"` the source MUST force a refresh
+ * (do not return a cached value); this is how the SDK recovers from
+ * 401s caused by a token that the server already invalidated.
+ *
+ * Implementations should be safe to call from many concurrent requests.
+ */
+type TokenSource = (reason?: TokenRequestReason) => Promise<string>;
+/** Caller-supplied options for `MantyxOAuthClient`. */
+interface MantyxOAuthClientOptions {
+    /**
+     * OAuth `client_id` issued at app registration (token prefix
+     * `mantyx_oa_`).
+     */
+    clientId: string;
+    /**
+     * OAuth `client_secret` issued at app registration (token prefix
+     * `mantyx_oas_`). Every MANTYX OAuth app is a confidential client,
+     * so this is always required for token + revoke calls. Treat as a
+     * deployment secret — do not bundle into browser builds.
+     */
+    clientSecret: string;
+    /**
+     * Origin of the MANTYX deployment. Defaults to `https://app.mantyx.io`.
+     * The OAuth endpoints are mounted at `<baseUrl>/api/oauth/...`.
+     */
+    baseUrl?: string;
+    /** Optional `fetch` override (e.g. node-fetch wrapper). Default: global `fetch`. */
+    fetch?: typeof fetch;
+    /** Default per-request timeout in milliseconds. Default: 30s. */
+    timeoutMs?: number;
+}
+interface RefreshOptions {
+    refreshToken: string;
+    /**
+     * Optional scope narrowing. Must be a subset of the scopes already
+     * granted to the refresh token (server enforces this). Useful when
+     * an SDK consumer wants a short-scope access token for a specific
+     * sub-operation.
+     */
+    scope?: string | readonly string[];
+}
+interface RevokeOptions {
+    token: string;
+}
+interface RefreshTokenSourceOptions {
+    refreshToken: string;
+    /** Optional scope narrowing applied on every refresh. */
+    scope?: string | readonly string[];
+    /**
+     * How many ms before `expiresAt` the source proactively refreshes.
+     * Defaults to {@link DEFAULT_REFRESH_SKEW_MS} (60s).
+     */
+    refreshSkewMs?: number;
+    /**
+     * Optional initial access token + expiry to seed the source's cache
+     * with (e.g. the token already in hand from the host application's
+     * sign-in flow). When omitted, the source mints one on the first
+     * call.
+     */
+    initialToken?: OAuthToken;
+}
+/**
+ * Refresh-only wrapper around the MANTYX OAuth 2.0 authorization-server
+ * endpoints. App-scoped (one per `{clientId, clientSecret}` pair);
+ * construct independently of {@link MantyxClient}, then either call
+ * {@link refresh} / {@link revoke} directly or hand a `TokenSource`
+ * produced by {@link refreshTokenSource} to `MantyxClient` for fully
+ * transparent refresh on every request.
+ *
+ * The client deliberately does **not** drive the authorization-code
+ * exchange or any other "initiate sign-in" grant. The caller is
+ * expected to obtain the refresh token through their own consent flow
+ * and persist it before constructing this client.
+ */
+declare class MantyxOAuthClient {
+    readonly clientId: string;
+    readonly baseUrl: string;
+    private readonly clientSecret;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: MantyxOAuthClientOptions);
+    /**
+     * Mint a fresh access token from a stored refresh token. The
+     * returned `refreshToken` is identical to the input — refresh
+     * tokens are persistent and non-rotating, so the field is
+     * surfaced only for symmetry with the response shape.
+     *
+     * On `400 invalid_grant` the refresh token has been revoked (or its
+     * grant / app was deleted); the SDK surfaces a
+     * {@link MantyxOAuthError} and callers must drive a fresh sign-in.
+     */
+    refresh(opts: RefreshOptions): Promise<OAuthToken>;
+    /**
+     * Revoke an access or refresh token (RFC 7009). The server always
+     * returns 200, even for unknown tokens. Revoking a **refresh**
+     * token kills the refresh and every live access token tied to its
+     * grant; revoking an **access** token kills only that one.
+     */
+    revoke(opts: RevokeOptions): Promise<void>;
+    /**
+     * Build a long-lived {@link TokenSource} that re-mints access
+     * tokens from the supplied refresh token. Pass the returned source
+     * to `new MantyxClient({ tokenSource, workspaceSlug, ... })`. The
+     * source caches the access token in-memory and refreshes
+     * proactively when the cached value is within `refreshSkewMs` of
+     * `expiresAt`, or eagerly when `MantyxClient` reports a 401.
+     *
+     * Pass `initialToken` if the calling app already has a non-expired
+     * access token in hand (e.g. straight out of the sign-in flow) to
+     * avoid an extra round-trip on the first request.
+     */
+    refreshTokenSource(opts: RefreshTokenSourceOptions): TokenSource;
+    /**
+     * POST `application/x-www-form-urlencoded` to `/api/oauth/token` and
+     * decode the {@link OAuthToken} response. Always injects `client_id`
+     * + `client_secret` from the constructor.
+     */
+    private token;
+    private formPost;
+}
+
 /**
  * Public tool helpers for the MANTYX SDK.
  *
@@ -332,7 +633,64 @@ declare function isLocalMcpServer(t: ToolRef): t is LocalMcpServer;
 
 declare const DEFAULT_BASE_URL = "https://app.mantyx.io";
 interface MantyxClientOptions {
-    apiKey: string;
+    /**
+     * Workspace API key (token prefix `mantyx_`) **or** a MANTYX OAuth 2.0
+     * access token (token prefix `mantyx_at_`). The server resolves either
+     * kind by token-prefix, so the SDK uses a single credential code path.
+     *
+     * Prefer the {@link accessToken} alias when wiring up an OAuth-based
+     * application — the two options are semantically identical (the value
+     * is forwarded as `Authorization: Bearer <credential>`), but
+     * `accessToken` makes the intent obvious at the call site.
+     *
+     * Exactly one of `apiKey` / `accessToken` must be set. Passing both —
+     * even to the same value — throws `MantyxError` at construction time.
+     *
+     * See `docs/agent-runs-protocol.md` §2 for the full credential table
+     * (including which prefix means what, scope semantics, and the
+     * `insufficient_scope` 403 SDKs surface via
+     * {@link MantyxScopeError}).
+     */
+    apiKey?: string;
+    /**
+     * MANTYX OAuth 2.0 access token (token prefix `mantyx_at_…`). Exactly
+     * one of {@link apiKey} / `accessToken` / {@link tokenSource} must be
+     * set; passing more than one throws `MantyxError` at construction
+     * time.
+     *
+     * Functionally identical to {@link apiKey} — the SDK ships either
+     * value verbatim on `Authorization: Bearer <credential>` — but using
+     * the OAuth-specific name makes scope-driven applications easier to
+     * read.
+     *
+     * OAuth tokens additionally enforce per-route **scopes**
+     * (`runs:read`, `runs:write`, `sessions:read`, `sessions:write`,
+     * `models:read`, `mantyx.identity:read`); see
+     * `docs/agent-runs-protocol.md` §2.2 for the table. Missing scopes
+     * land as {@link MantyxScopeError} so callers can route the user
+     * back to a re-consent flow.
+     *
+     * Static `accessToken` values are 1-hour-lived per `docs/oauth.md`
+     * §"Token lifetimes & lifecycle" — for long-running processes
+     * prefer {@link tokenSource} so the SDK can refresh transparently.
+     */
+    accessToken?: string;
+    /**
+     * Dynamic credential provider. The SDK calls it before every request
+     * to obtain the current access token, and again with
+     * `reason: "unauthorized"` after a 401 so it can refresh and retry
+     * the request exactly once.
+     *
+     * Build one via `oauthClient.refreshTokenSource({ refreshToken })`
+     * or `oauthClient.clientCredentialsTokenSource()` — see
+     * [`./oauth.ts`](./oauth.ts) for the helpers, or pass any function
+     * matching the {@link TokenSource} signature for full custom
+     * control (e.g. tokens minted by an upstream auth proxy).
+     *
+     * Exactly one of {@link apiKey} / {@link accessToken} / `tokenSource`
+     * must be set.
+     */
+    tokenSource?: TokenSource;
     workspaceSlug: string;
     /** Defaults to `https://app.mantyx.io`. Override for self-hosted instances. */
     baseUrl?: string;
@@ -741,9 +1099,28 @@ interface SessionInfo {
     metadata: Record<string, string>;
 }
 declare class MantyxClient {
-    readonly options: Required<Pick<MantyxClientOptions, "apiKey" | "workspaceSlug" | "baseUrl">> & {
+    readonly options: Required<Pick<MantyxClientOptions, "workspaceSlug" | "baseUrl">> & {
+        /**
+         * Single resolved bearer credential — either a workspace API key
+         * (token prefix `mantyx_`) or an OAuth access token (`mantyx_at_…`).
+         * The SDK does not need to distinguish them on the wire; the value
+         * is forwarded verbatim on `Authorization: Bearer …`.
+         *
+         * Kept as `apiKey` (instead of e.g. `credential`) for backwards
+         * compatibility — older releases exposed it under this name.
+         *
+         * Empty string when a {@link tokenSource} is configured — every
+         * request resolves the bearer from the source instead.
+         */
+        apiKey: string;
         fetch: typeof fetch;
         timeoutMs: number;
+        /**
+         * Dynamic credential provider when constructed with
+         * `tokenSource` — see {@link MantyxClientOptions.tokenSource}.
+         * `null` for static `apiKey` / `accessToken` clients.
+         */
+        tokenSource: TokenSource | null;
     };
     constructor(opts: MantyxClientOptions);
     listModels(): Promise<ModelCatalog>;
@@ -779,6 +1156,26 @@ declare class MantyxClient {
     }): Promise<void>;
     cancelRun(runId: string): Promise<void>;
     private absoluteUrl;
+    /**
+     * Resolve the bearer credential to send on the next request. With a
+     * static `apiKey` / `accessToken` this is a synchronous reach into
+     * `options.apiKey`; with a {@link TokenSource} it delegates so the
+     * source can refresh expired access tokens before we hit the wire.
+     *
+     * The `reason` is forwarded to the source verbatim. Pass
+     * `"unauthorized"` immediately after a 401 so the source forces a
+     * refresh rather than handing back its (now-invalid) cached value.
+     */
+    private resolveBearer;
+    /**
+     * Open an SSE stream against `reqUrl` with at-most-one refresh +
+     * retry on 401. The caller is responsible for the subsequent
+     * `readSseStream` loop; this helper only handles the initial GET.
+     * Mid-stream 401s propagate as `MantyxNetworkError` from the read
+     * loop and trigger a reconnect via the outer `while` in
+     * {@link streamRunEvents}.
+     */
+    private openSseStream;
     private authHeaders;
     request<T>(args: {
         method: string;
@@ -786,6 +1183,7 @@ declare class MantyxClient {
         body?: unknown;
         timeoutMs?: number;
     }): Promise<T>;
+    private requestWithRetry;
     private errorFromResponse;
 }
 declare class AgentSession {
@@ -882,4 +1280,4 @@ interface LocalHandlers {
  */
 declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
 
-export { mantyxMcp as $, type A2AToolRef as A, type RunEventBase as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, type RunResult as F, type RunSpec as G, type SessionInfo as H, type SessionSpec as I, type ThinkingDeltaEvent as J, type ToolBudget as K, type LocalA2ATool as L, MantyxClient as M, type ToolBudgetExceededEvent as N, type OutputSchema as O, type ToolBudgets as P, defineLocalA2A as Q, type ReasoningLevel as R, type ServerToolResultEvent as S, type ToolRef as T, defineLocalMcp as U, defineLocalTool as V, isLocalA2ATool as W, isLocalMcpServer as X, isLocalTool as Y, type ZodLikeObject as Z, mantyxA2A as _, AgentSession as a, mantyxPluginTool as a0, mantyxTool as a1, parseRunOutput as a2, 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 LoopDetectedEvent as o, type LoopDetection as p, type MantyxA2AOptions as q, type MantyxClientOptions as r, type MantyxMcpOptions as s, type MantyxPluginToolRef as t, type MantyxToolRef as u, type McpToolRef as v, type ModelCatalog as w, type ModelInfo as x, type ResultEvent as y, type RunEvent as z };
+export { type RunResult as $, type A2AToolRef as A, MantyxOAuthError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxParseError as F, type MantyxPluginToolRef as G, MantyxRunError as H, type MantyxRunErrorInit as I, MantyxScopeError as J, MantyxToolError as K, type LocalA2ATool as L, MantyxClient as M, type MantyxToolRef as N, type McpToolRef as O, type ModelCatalog as P, type ModelInfo as Q, type ReasoningLevel as R, type OAuthToken as S, type ToolRef as T, type OutputSchema as U, type RefreshOptions as V, type RefreshTokenSourceOptions as W, type ResultEvent as X, type RevokeOptions as Y, type RunEvent as Z, type RunEventBase as _, AgentSession as a, type RunSpec as a0, type ServerToolResultEvent as a1, type SessionInfo as a2, type SessionSpec as a3, type ThinkingDeltaEvent as a4, type TokenRequestReason as a5, type TokenSource as a6, type ToolBudget as a7, type ToolBudgetExceededEvent as a8, type ToolBudgets as a9, type ZodLikeObject as aa, defineLocalA2A as ab, defineLocalMcp as ac, defineLocalTool as ad, isLocalA2ATool as ae, isLocalMcpServer as af, isLocalTool as ag, mantyxA2A as ah, mantyxMcp as ai, mantyxPluginTool as aj, mantyxTool as ak, parseRunOutput as al, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, DEFAULT_OAUTH_BASE_URL as e, DEFAULT_REFRESH_SKEW_MS as f, type DefineLocalA2AOptions as g, type DefineLocalMcpOptions as h, type DefineLocalToolOptions as i, type LocalHandlers as j, type LocalMcpHttpTransport as k, type LocalMcpServer as l, type LocalMcpStdioTransport as m, type LocalTool as n, type LocalToolCallEvent as o, type LocalToolResultInEvent as p, type LoopDetectedEvent as q, type LoopDetection as r, type MantyxA2AOptions as s, MantyxAuthError as t, type MantyxClientOptions as u, MantyxError as v, type MantyxMcpOptions as w, MantyxNetworkError as x, MantyxOAuthClient as y, type MantyxOAuthClientOptions as z };