@mantyx/sdk 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.10.0] — 2026-05-13
 
 ### Added
 
@@ -80,7 +80,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.0] — 2026-05-02
 
-[unreleased]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.9.1..HEAD
+[0.10.0]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.9.1..v0.10.0
 [0.9.1]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.9.0..v0.9.1
 [0.9.0]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.8.0..v0.9.0
 [0.8.0]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.7.0..v0.8.0

package/README.md

@@ -555,58 +555,64 @@ All thrown errors extend `MantyxError`. Common subclasses:
 
 ### OAuth 2.0 refresh
 
-For long-running services, hand the SDK a `TokenSource` instead of a
-static `accessToken` — the client refreshes proactively before
-expiry and again on 401, retrying the original request exactly once.
-Refresh tokens are **persistent and non-rotating** per
-[`docs/oauth.md`](./docs/oauth.md): the caller persists the
-`refreshToken` once at first sign-in (treat it as long-lived,
-encrypted at rest) and the SDK re-mints access tokens from it
-transparently.
+The SDK ships a **refresh-only** OAuth client. It assumes the calling
+app already obtained a refresh token through its own sign-in flow
+(browser PKCE redirect, native auth, server-side exchange — whatever
+fits the host). The library does not drive consent and does not
+initiate authorization-code or client-credentials grants. Once you
+have the refresh token, hand it to the SDK and the rest is
+transparent:
+
+- Refresh tokens are **persistent and non-rotating** per
+  [`docs/oauth.md`](./docs/oauth.md): store them once at first
+  sign-in (treat them as long-lived, encrypted at rest) and the SDK
+  re-mints access tokens from the same value on demand.
+- A `TokenSource` is called before every request and again on `401`,
+  with single-flight collapse on concurrent refreshes.
+- `400 invalid_grant` from the token endpoint is surfaced as
+  `MantyxOAuthError` — that means the refresh has been revoked and
+  the caller has to drive a fresh sign-in.
 
 ```ts
 import { MantyxClient, MantyxOAuthClient } from "@mantyx/sdk";
 
 const oauth = new MantyxOAuthClient({
-  clientId: process.env.MANTYX_OAUTH_CLIENT_ID!,        // mantyx_oa_…
+  clientId: process.env.MANTYX_OAUTH_CLIENT_ID!,         // mantyx_oa_…
   clientSecret: process.env.MANTYX_OAUTH_CLIENT_SECRET!, // mantyx_oas_…
 });
 
-// (1) Authorization-code: swap a `code` for the initial token pair, persist
-//     the refresh token against the user record. See docs/oauth.md for the
-//     full PKCE redirect dance the calling app is responsible for.
-const initial = await oauth.exchangeAuthorizationCode({
-  code: authCode,
-  redirectUri: "https://app.example.com/cb",
-  codeVerifier: storedVerifier,
-});
-await db.users.update(userId, { mantyxRefreshToken: initial.refreshToken });
-
-// (2) End-user clients: build a refresh-driven TokenSource from the
-//     persisted refresh token. The SDK calls it before every request and on
-//     401s; concurrent requests collapse onto one refresh.
+// (1) Hand the SDK a stored refresh token — it caches the access token in
+//     memory, refreshes proactively before expiry, and retries the original
+//     request once on a 401.
 const client = new MantyxClient({
   tokenSource: oauth.refreshTokenSource({
-    refreshToken: initial.refreshToken!,
-    initialToken: initial,
+    refreshToken: storedRefreshToken,                    // mantyx_rt_…
   }),
   workspaceSlug: "acme",
 });
 
-// (3) Service-to-service: client_credentials sources never hold a refresh
-//     token; they re-mint access tokens on demand.
-const svcClient = new MantyxClient({
-  tokenSource: oauth.clientCredentialsTokenSource({ scope: ["agents:invoke"] }),
+// (2) If the calling app already has a non-expired access token in hand
+//     (e.g. straight out of its sign-in flow), pass it as `initialToken` to
+//     skip the first /token round-trip.
+const seeded = new MantyxClient({
+  tokenSource: oauth.refreshTokenSource({
+    refreshToken: storedRefreshToken,
+    initialToken: tokenFromSignIn,
+  }),
   workspaceSlug: "acme",
 });
 
-// (4) Manual override is still supported for short-lived access tokens that
-//     the caller already manages.
+// (3) Manual override for short-lived access tokens the caller manages
+//     itself — no refresh, no retry, no OAuth client needed.
 const oneShot = new MantyxClient({ accessToken: "mantyx_at_…", workspaceSlug: "acme" });
+
+// Optional: revoke a refresh token at sign-out — this kills the refresh and
+// every live access token tied to its grant.
+await oauth.revoke({ token: storedRefreshToken });
 ```
 
 See [`docs/oauth.md`](./docs/oauth.md) for grant types, token formats,
-and revocation.
+scope catalog, and revocation semantics.
 
 ## Examples
 

package/dist/a2a-server.d.cts

@@ -2,7 +2,7 @@ import { AgentCard } from '@a2a-js/sdk';
 export { AgentCard, Message, MessageSendParams, Task, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from '@a2a-js/sdk';
 import { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
 export { AgentExecutor, ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
-import { M as MantyxClient, T as ToolRef, R as ReasoningLevel } from './client-DHwh8MPj.cjs';
+import { M as MantyxClient, T as ToolRef, R as ReasoningLevel } from './client-CZUVldDx.cjs';
 import 'zod';
 
 /**

package/dist/a2a-server.d.ts

@@ -2,7 +2,7 @@ import { AgentCard } from '@a2a-js/sdk';
 export { AgentCard, Message, MessageSendParams, Task, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from '@a2a-js/sdk';
 import { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
 export { AgentExecutor, ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
-import { M as MantyxClient, T as ToolRef, R as ReasoningLevel } from './client-DHwh8MPj.js';
+import { M as MantyxClient, T as ToolRef, R as ReasoningLevel } from './client-CZUVldDx.js';
 import 'zod';
 
 /**

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

@@ -113,26 +113,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 +159,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 +211,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 +221,6 @@ interface RefreshOptions {
      */
     scope?: string | readonly string[];
 }
-interface ClientCredentialsOptions {
-    scope?: string | readonly string[];
-}
 interface RevokeOptions {
     token: string;
 }
@@ -241,21 +235,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 +261,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 +286,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 +300,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.
@@ -1319,4 +1280,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 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 };

package/dist/{client-DHwh8MPj.d.ts → client-CZUVldDx.d.ts}

@@ -113,26 +113,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 +159,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 +211,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 +221,6 @@ interface RefreshOptions {
      */
     scope?: string | readonly string[];
 }
-interface ClientCredentialsOptions {
-    scope?: string | readonly string[];
-}
 interface RevokeOptions {
     token: string;
 }
@@ -241,21 +235,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 +261,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 +286,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 +300,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.
@@ -1319,4 +1280,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 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 };