@mantyx/sdk 0.10.0 → 0.11.0

package/dist/{client-DHwh8MPj.d.cts → client-Byb0Zdo7.d.cts}

@@ -47,6 +47,30 @@ declare class MantyxToolError extends MantyxError {
     readonly toolName: string;
     constructor(toolName: string, message: string);
 }
+/**
+ * Per-run token totals attached to terminal `result` / `error`
+ * events. See `docs/agent-runs-protocol.md` §7.1 for the per-provider
+ * mapping and the relationship between buckets. Re-exported from
+ * `client.ts` so error consumers can pattern-match the triple without
+ * a second import.
+ */
+interface MantyxRunErrorTokens {
+    inputTokens: number;
+    cachedTokens: number;
+    reasoningTokens: number;
+    outputTokens: number;
+}
+/**
+ * Resolved model that executed the run. Surfaced on terminal events
+ * by MANTYX ≥ 2026-09. See `docs/agent-runs-protocol.md` §7.1. The
+ * `provider` empty / undefined is the "no usage data" sentinel.
+ */
+interface MantyxRunErrorModel {
+    id: string;
+    provider: string;
+    vendorModelId: string;
+    reasoningEffort?: string;
+}
 /**
  * Optional triage attributes the runner attaches to terminal `error`
  * events. Mirrors the wire fields described in
@@ -83,6 +107,17 @@ interface MantyxRunErrorInit {
      * Informational; the SDK still owns the actual retry decision.
      */
     retryable?: boolean;
+    /**
+     * Per-run token totals from the terminal event. Present against
+     * MANTYX ≥ 2026-09 — see {@link MantyxRunErrorTokens} and
+     * `docs/agent-runs-protocol.md` §7.1. Includes the failing model
+     * call's usage when the run errored mid-loop.
+     */
+    tokens?: MantyxRunErrorTokens;
+    /** Total model invocations for the run, including the failing call. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link MantyxRunErrorModel}. */
+    model?: MantyxRunErrorModel;
 }
 declare class MantyxRunError extends MantyxError {
     readonly runId: string;
@@ -95,6 +130,12 @@ declare class MantyxRunError extends MantyxError {
     readonly partialText: string | undefined;
     /** See {@link MantyxRunErrorInit.retryable}. */
     readonly retryable: boolean | undefined;
+    /** See {@link MantyxRunErrorInit.tokens}. */
+    readonly tokens: MantyxRunErrorTokens | undefined;
+    /** See {@link MantyxRunErrorInit.turns}. */
+    readonly turns: number | undefined;
+    /** See {@link MantyxRunErrorInit.model}. */
+    readonly model: MantyxRunErrorModel | undefined;
     constructor(runId: string, subtype: string, message: string, init?: MantyxRunErrorInit);
 }
 /**
@@ -113,26 +154,28 @@ declare class MantyxParseError extends MantyxError {
 }
 
 /**
- * MANTYX OAuth 2.0 client: authorization-code exchange, refresh-token
- * minting, client-credentials grant, and token revocation, plus typed
- * {@link TokenSource}s that {@link MantyxClient} can consume to refresh
- * access tokens transparently before they expire (and again on 401).
+ * 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 wire contract this implements is `docs/oauth.md` in the SDK monorepo:
+ * 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.
  *
- * - Token endpoint: `POST <baseUrl>/api/oauth/token`, form-encoded.
+ * 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 **persistent and non-rotating**:
- *   `grant_type=refresh_token` echoes back the same value the client
- *   sent. The caller persists the refresh token once at first sign-in
- *   (encrypted at rest) and the SDK re-mints access tokens from it on
- *   demand.
- *
- * See also `docs/oauth.md` for the authorization-code + PKCE consent
- * flow (which the SDK does **not** drive — the calling app owns the
- * redirect dance; once it has the auth code, `exchangeAuthorizationCode`
- * swaps it for the initial `{access_token, refresh_token}` pair).
+ * - 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";
@@ -157,12 +200,12 @@ declare class MantyxOAuthError extends MantyxError {
 }
 /**
  * Decoded `POST /api/oauth/token` response, augmented with an absolute
- * `expiresAt` timestamp the SDK can use to decide when to refresh.
+ * `expiresAt` timestamp the SDK uses to decide when to refresh.
  *
- * `refreshToken` is present on the initial `authorization_code` exchange
- * and on subsequent `refresh_token` calls (where it is identical to the
- * value the client just sent — refresh tokens never rotate). The
- * `client_credentials` grant never returns one.
+ * 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;
@@ -209,11 +252,6 @@ interface MantyxOAuthClientOptions {
     /** Default per-request timeout in milliseconds. Default: 30s. */
     timeoutMs?: number;
 }
-interface ExchangeAuthorizationCodeOptions {
-    code: string;
-    redirectUri: string;
-    codeVerifier: string;
-}
 interface RefreshOptions {
     refreshToken: string;
     /**
@@ -224,9 +262,6 @@ interface RefreshOptions {
      */
     scope?: string | readonly string[];
 }
-interface ClientCredentialsOptions {
-    scope?: string | readonly string[];
-}
 interface RevokeOptions {
     token: string;
 }
@@ -241,21 +276,24 @@ interface RefreshTokenSourceOptions {
     refreshSkewMs?: number;
     /**
      * Optional initial access token + expiry to seed the source's cache
-     * with (e.g. the token already in hand from the authorization-code
-     * exchange). When omitted, the source mints one on the first call.
+     * 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;
 }
-interface ClientCredentialsTokenSourceOptions {
-    scope?: string | readonly string[];
-    refreshSkewMs?: number;
-}
 /**
- * Wraps the MANTYX OAuth 2.0 authorization-server endpoints. App-scoped
- * (one per `{clientId, clientSecret}` pair); construct independently of
- * {@link MantyxClient}, then either call its grant helpers directly or
- * hand a `TokenSource` it produces to `MantyxClient` for fully
- * transparent refresh.
+ * 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;
@@ -264,33 +302,17 @@ declare class MantyxOAuthClient {
     private readonly fetchImpl;
     private readonly timeoutMs;
     constructor(opts: MantyxOAuthClientOptions);
-    /**
-     * Swap an authorization-code + PKCE verifier for the initial
-     * `{access_token, refresh_token}` pair. Call this exactly once per
-     * sign-in after the browser/native redirect lands back on your
-     * `redirectUri` with a `code` parameter. Persist the returned
-     * `refreshToken` against the user record — it is long-lived and
-     * non-rotating per `docs/oauth.md` §"Token lifetimes & lifecycle".
-     */
-    exchangeAuthorizationCode(opts: ExchangeAuthorizationCodeOptions): Promise<OAuthToken>;
     /**
      * Mint a fresh access token from a stored refresh token. The
-     * returned `refreshToken` is identical to the input — the field is
-     * surfaced for symmetry with {@link exchangeAuthorizationCode} only.
+     * 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>;
-    /**
-     * Request a workspace-scoped access token without a user via the
-     * `client_credentials` grant. Available only on private OAuth apps
-     * that were registered with `allowsClientCredentials: true`. No
-     * refresh token is issued; re-call this method whenever a new
-     * access token is needed.
-     */
-    clientCredentials(opts?: ClientCredentialsOptions): Promise<OAuthToken>;
     /**
      * Revoke an access or refresh token (RFC 7009). The server always
      * returns 200, even for unknown tokens. Revoking a **refresh**
@@ -305,16 +327,12 @@ declare class MantyxOAuthClient {
      * 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;
-    /**
-     * Build a long-lived {@link TokenSource} backed by the
-     * `client_credentials` grant. On every refresh the source re-mints
-     * a workspace-scoped access token by calling the token endpoint
-     * with `grant_type=client_credentials`. Available only on private
-     * apps with `allowsClientCredentials: true`.
-     */
-    clientCredentialsTokenSource(opts?: ClientCredentialsTokenSourceOptions): TokenSource;
     /**
      * POST `application/x-www-form-urlencoded` to `/api/oauth/token` and
      * decode the {@link OAuthToken} response. Always injects `client_id`
@@ -323,22 +341,6 @@ declare class MantyxOAuthClient {
     private token;
     private formPost;
 }
-/**
- * Generate a high-entropy PKCE `code_verifier` (RFC 7636 §4.1). The
- * verifier is the raw secret you keep across the redirect; the
- * `code_challenge` you send on `/api/oauth/authorize` is derived from
- * it via {@link pkceChallenge}.
- *
- * Default length is 64 characters (≈ 384 bits of entropy after
- * base64url-encoding the 32 random bytes). Pass `length` to clamp to
- * the RFC's 43..128 inclusive range.
- */
-declare function generatePkceVerifier(length?: number): string;
-/**
- * Compute the PKCE `S256` `code_challenge` for a given verifier:
- * `base64url(sha256(verifier))` with no padding (RFC 7636 §4.2).
- */
-declare function pkceChallenge(verifier: string): string;
 
 /**
  * Public tool helpers for the MANTYX SDK.
@@ -923,10 +925,102 @@ interface ToolBudget {
  * entirely to keep the defaults.
  */
 type ToolBudgets = Record<string, ToolBudget>;
+/**
+ * Per-run token totals attached to terminal `result` / `error` events
+ * (and to the `GET /agent-runs/:runId` snapshot) by MANTYX ≥ 2026-09.
+ *
+ * Aggregated across every model invocation for the run. See
+ * `docs/agent-runs-protocol.md` §7.1 for the per-provider mapping and
+ * the relationship between buckets (`inputTokens` / `outputTokens` are
+ * the billable totals; `cachedTokens` and `reasoningTokens` are
+ * diagnostic breakdowns _inside_ those two totals, not separate
+ * additive buckets).
+ *
+ * Older servers omit the cost-attribution triple entirely; SDK callers
+ * detect "no usage data" by checking `result.model?.provider` is empty
+ * / undefined.
+ */
+interface RunTokenUsage {
+    /**
+     * Total billable input tokens — fresh prompt tokens plus the
+     * cached-read slice the provider still bills (at a discount) plus
+     * any cache-creation tokens plus tool-prompt tokens. Equal to the
+     * sum of every provider-reported input bucket for the run.
+     */
+    inputTokens: number;
+    /**
+     * The discounted slice of `inputTokens` that came from a prompt
+     * cache hit (Anthropic prompt caching, OpenAI cached prompt, Gemini
+     * implicit cache). `0` when the provider doesn't report cache reads
+     * or the run didn't hit cache.
+     */
+    cachedTokens: number;
+    /**
+     * Non-visible thinking tokens. **Already counted inside
+     * `outputTokens`** — surfaced separately so dashboards can break out
+     * "thinking cost" vs visible output. `0` when the model didn't
+     * reason or didn't report it.
+     */
+    reasoningTokens: number;
+    /**
+     * All tokens the model emitted for this run, visible + reasoning.
+     * Matches the provider's "completion tokens" / "output tokens"
+     * billing line.
+     */
+    outputTokens: number;
+}
+/**
+ * The resolved model the platform stamped onto the run, surfaced on
+ * terminal `result` / `error` events (and `GET /agent-runs/:runId`)
+ * by MANTYX ≥ 2026-09. See `docs/agent-runs-protocol.md` §7.1.
+ */
+interface RunModelInfo {
+    /**
+     * Catalog id — the same string a caller would pass back as
+     * `modelId` to re-select this exact entry (e.g. `"platform:demo"`,
+     * `"provider:cmf…"`). Empty string against legacy fallbacks that
+     * didn't synthesise a catalog id.
+     */
+    id: string;
+    /**
+     * Lowercase provider id: `"openai"`, `"anthropic"`, `"google"`,
+     * `"azure-openai"`. Empty string against legacy runners that don't
+     * report usage data — SDK callers use that as the "no usage data"
+     * signal.
+     */
+    provider: string;
+    /**
+     * The model id the platform actually sent to the provider (e.g.
+     * `"gpt-5.4-mini"`, `"claude-opus-4-7"`, `"gemini-2.5-pro"`).
+     */
+    vendorModelId: string;
+    /**
+     * `"off" | "low" | "medium" | "high"`. Omitted when the provider
+     * doesn't expose a reasoning-level knob or the run didn't request
+     * one.
+     */
+    reasoningEffort?: string;
+}
 interface RunResult {
     runId: string;
     text: string;
     events: RunEvent[];
+    /**
+     * Per-run token totals from the terminal event. Undefined against
+     * MANTYX servers older than 2026-09 (the "no usage data" signal is
+     * `result.model?.provider` being empty / undefined). See
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     */
+    tokens?: RunTokenUsage;
+    /**
+     * Total `engine.completeTurn(...)` invocations for the run,
+     * including the failing call when a run errored mid-loop. A
+     * single-shot run reports `1`; a tool loop is `>= 2`. Undefined
+     * against legacy MANTYX servers.
+     */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface RunEventBase {
     seq: number;
@@ -1075,6 +1169,15 @@ interface ResultEvent extends RunEventBase {
     subtype: string;
     text?: string;
     error?: string;
+    /**
+     * Per-run token totals. Present against MANTYX ≥ 2026-09 — see
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     */
+    tokens?: RunTokenUsage;
+    /** Total model invocations for the run. See {@link RunResult.turns}. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface ErrorEvent extends RunEventBase {
     type: "error";
@@ -1113,6 +1216,18 @@ interface ErrorEvent extends RunEventBase {
      * Informational; the SDK still owns the actual retry decision.
      */
     retryable?: boolean;
+    /**
+     * Per-run token totals. Present against MANTYX ≥ 2026-09 — see
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     * The pipeline counts the failing model call too, so a run that
+     * threw on the first turn reports `turns: 1` with that call's
+     * tokens already aggregated.
+     */
+    tokens?: RunTokenUsage;
+    /** Total model invocations for the run, including the failing call. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface CancelledEvent extends RunEventBase {
     type: "cancelled";
@@ -1319,4 +1434,4 @@ interface LocalHandlers {
  */
 declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
 
-export { type RevokeOptions as $, type A2AToolRef as A, MantyxNetworkError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxOAuthClient as F, type MantyxOAuthClientOptions as G, MantyxOAuthError as H, MantyxParseError as I, type MantyxPluginToolRef as J, MantyxRunError as K, type LocalA2ATool as L, MantyxClient as M, type MantyxRunErrorInit as N, MantyxScopeError as O, MantyxToolError as P, type MantyxToolRef as Q, type ReasoningLevel as R, type McpToolRef as S, type ToolRef as T, type ModelCatalog as U, type ModelInfo as V, type OAuthToken as W, type OutputSchema as X, type RefreshOptions as Y, type RefreshTokenSourceOptions as Z, type ResultEvent as _, AgentSession as a, type RunEvent as a0, type RunEventBase as a1, type RunResult as a2, type RunSpec as a3, type ServerToolResultEvent as a4, type SessionInfo as a5, type SessionSpec as a6, type ThinkingDeltaEvent as a7, type TokenRequestReason as a8, type TokenSource as a9, type ToolBudget as aa, type ToolBudgetExceededEvent as ab, type ToolBudgets as ac, type ZodLikeObject as ad, defineLocalA2A as ae, defineLocalMcp as af, defineLocalTool as ag, generatePkceVerifier as ah, isLocalA2ATool as ai, isLocalMcpServer as aj, isLocalTool as ak, mantyxA2A as al, mantyxMcp as am, mantyxPluginTool as an, mantyxTool as ao, parseRunOutput as ap, pkceChallenge as aq, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, type ClientCredentialsOptions as e, type ClientCredentialsTokenSourceOptions as f, DEFAULT_OAUTH_BASE_URL as g, DEFAULT_REFRESH_SKEW_MS as h, type DefineLocalA2AOptions as i, type DefineLocalMcpOptions as j, type DefineLocalToolOptions as k, type ExchangeAuthorizationCodeOptions as l, type LocalHandlers as m, type LocalMcpHttpTransport as n, type LocalMcpServer as o, type LocalMcpStdioTransport as p, type LocalTool as q, type LocalToolCallEvent as r, type LocalToolResultInEvent as s, type LoopDetectedEvent as t, type LoopDetection as u, type MantyxA2AOptions as v, MantyxAuthError as w, type MantyxClientOptions as x, MantyxError as y, type MantyxMcpOptions as z };
+export { type RunEvent 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, type MantyxRunErrorModel as J, type MantyxRunErrorTokens as K, type LocalA2ATool as L, MantyxClient as M, MantyxScopeError as N, MantyxToolError as O, type MantyxToolRef as P, type McpToolRef as Q, type ReasoningLevel as R, type ModelCatalog as S, type ToolRef as T, type ModelInfo as U, type OAuthToken as V, type OutputSchema as W, type RefreshOptions as X, type RefreshTokenSourceOptions as Y, type ResultEvent as Z, type RevokeOptions as _, AgentSession as a, type RunEventBase as a0, type RunModelInfo as a1, type RunResult as a2, type RunSpec as a3, type RunTokenUsage as a4, type ServerToolResultEvent as a5, type SessionInfo as a6, type SessionSpec as a7, type ThinkingDeltaEvent as a8, type TokenRequestReason as a9, type TokenSource as aa, type ToolBudget as ab, type ToolBudgetExceededEvent as ac, type ToolBudgets as ad, type ZodLikeObject as ae, defineLocalA2A as af, defineLocalMcp as ag, defineLocalTool as ah, isLocalA2ATool as ai, isLocalMcpServer as aj, isLocalTool as ak, mantyxA2A as al, mantyxMcp as am, mantyxPluginTool as an, mantyxTool as ao, parseRunOutput as ap, 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 };