@mantyx/sdk 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -1,51 +1,6 @@
-export { A as A2AToolRef, a as AgentSession, b as AgentSpecBase, c as AssistantDeltaEvent, d as AssistantMessageEvent, C as CancelledEvent, D as DEFAULT_BASE_URL, e as DefineLocalA2AOptions, f as DefineLocalMcpOptions, g as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, h as LocalHandlers, i as LocalMcpHttpTransport, j as LocalMcpServer, k as LocalMcpStdioTransport, l as LocalTool, m as LocalToolCallEvent, n as LocalToolResultInEvent, o as LoopDetectedEvent, p as LoopDetection, q as MantyxA2AOptions, M as MantyxClient, r as MantyxClientOptions, s as MantyxMcpOptions, t as MantyxPluginToolRef, u as MantyxToolRef, v as McpToolRef, w as ModelCatalog, x as ModelInfo, O as OutputSchema, R as ReasoningLevel, y as ResultEvent, z as RunEvent, B as RunEventBase, F as RunResult, G as RunSpec, S as ServerToolResultEvent, H as SessionInfo, I as SessionSpec, J as ThinkingDeltaEvent, K as ToolBudget, N as ToolBudgetExceededEvent, P as ToolBudgets, T as ToolRef, Z as ZodLikeObject, Q as defineLocalA2A, U as defineLocalMcp, V as defineLocalTool, W as isLocalA2ATool, X as isLocalMcpServer, Y as isLocalTool, _ as mantyxA2A, $ as mantyxMcp, a0 as mantyxPluginTool, a1 as mantyxTool, a2 as parseRunOutput } from './client-CeWCSsmD.cjs';
+export { A as A2AToolRef, a as AgentSession, b as AgentSpecBase, c as AssistantDeltaEvent, d as AssistantMessageEvent, C as CancelledEvent, e as ClientCredentialsOptions, f as ClientCredentialsTokenSourceOptions, D as DEFAULT_BASE_URL, g as DEFAULT_OAUTH_BASE_URL, h as DEFAULT_REFRESH_SKEW_MS, i as DefineLocalA2AOptions, j as DefineLocalMcpOptions, k as DefineLocalToolOptions, E as ErrorEvent, l as ExchangeAuthorizationCodeOptions, L as LocalA2ATool, m as LocalHandlers, n as LocalMcpHttpTransport, o as LocalMcpServer, p as LocalMcpStdioTransport, q as LocalTool, r as LocalToolCallEvent, s as LocalToolResultInEvent, t as LoopDetectedEvent, u as LoopDetection, v as MantyxA2AOptions, w as MantyxAuthError, M as MantyxClient, x as MantyxClientOptions, y as MantyxError, z as MantyxMcpOptions, B as MantyxNetworkError, F as MantyxOAuthClient, G as MantyxOAuthClientOptions, H as MantyxOAuthError, I as MantyxParseError, J as MantyxPluginToolRef, K as MantyxRunError, N as MantyxRunErrorInit, O as MantyxScopeError, P as MantyxToolError, Q as MantyxToolRef, S as McpToolRef, U as ModelCatalog, V as ModelInfo, W as OAuthToken, X as OutputSchema, R as ReasoningLevel, Y as RefreshOptions, Z as RefreshTokenSourceOptions, _ as ResultEvent, $ as RevokeOptions, a0 as RunEvent, a1 as RunEventBase, a2 as RunResult, a3 as RunSpec, a4 as ServerToolResultEvent, a5 as SessionInfo, a6 as SessionSpec, a7 as ThinkingDeltaEvent, a8 as TokenRequestReason, a9 as TokenSource, aa as ToolBudget, ab as ToolBudgetExceededEvent, ac as ToolBudgets, T as ToolRef, ad as ZodLikeObject, ae as defineLocalA2A, af as defineLocalMcp, ag as defineLocalTool, ah as generatePkceVerifier, ai as isLocalA2ATool, aj as isLocalMcpServer, ak as isLocalTool, al as mantyxA2A, am as mantyxMcp, an as mantyxPluginTool, ao as mantyxTool, ap as parseRunOutput, aq as pkceChallenge } from './client-DHwh8MPj.cjs';
 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);
-}
-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);
-}
-/**
- * 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;
-    });
-}
-
 /**
  * Lightweight Zod → JSON Schema converter for tool parameter definitions.
  *
@@ -97,6 +52,6 @@ declare function readSseStream(body: ReadableStream<Uint8Array> | null, opts?: S
 /**
  * Release version — synced from repo root VERSION (`npm run sync-version`).
  */
-declare const SDK_VERSION = "0.9.0";
+declare const SDK_VERSION = "0.10.0";
 
-export { MantyxAuthError, MantyxError, MantyxNetworkError, MantyxParseError, MantyxRunError, MantyxToolError, SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };
+export { SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };

package/dist/index.d.ts

@@ -1,51 +1,6 @@
-export { A as A2AToolRef, a as AgentSession, b as AgentSpecBase, c as AssistantDeltaEvent, d as AssistantMessageEvent, C as CancelledEvent, D as DEFAULT_BASE_URL, e as DefineLocalA2AOptions, f as DefineLocalMcpOptions, g as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, h as LocalHandlers, i as LocalMcpHttpTransport, j as LocalMcpServer, k as LocalMcpStdioTransport, l as LocalTool, m as LocalToolCallEvent, n as LocalToolResultInEvent, o as LoopDetectedEvent, p as LoopDetection, q as MantyxA2AOptions, M as MantyxClient, r as MantyxClientOptions, s as MantyxMcpOptions, t as MantyxPluginToolRef, u as MantyxToolRef, v as McpToolRef, w as ModelCatalog, x as ModelInfo, O as OutputSchema, R as ReasoningLevel, y as ResultEvent, z as RunEvent, B as RunEventBase, F as RunResult, G as RunSpec, S as ServerToolResultEvent, H as SessionInfo, I as SessionSpec, J as ThinkingDeltaEvent, K as ToolBudget, N as ToolBudgetExceededEvent, P as ToolBudgets, T as ToolRef, Z as ZodLikeObject, Q as defineLocalA2A, U as defineLocalMcp, V as defineLocalTool, W as isLocalA2ATool, X as isLocalMcpServer, Y as isLocalTool, _ as mantyxA2A, $ as mantyxMcp, a0 as mantyxPluginTool, a1 as mantyxTool, a2 as parseRunOutput } from './client-CeWCSsmD.js';
+export { A as A2AToolRef, a as AgentSession, b as AgentSpecBase, c as AssistantDeltaEvent, d as AssistantMessageEvent, C as CancelledEvent, e as ClientCredentialsOptions, f as ClientCredentialsTokenSourceOptions, D as DEFAULT_BASE_URL, g as DEFAULT_OAUTH_BASE_URL, h as DEFAULT_REFRESH_SKEW_MS, i as DefineLocalA2AOptions, j as DefineLocalMcpOptions, k as DefineLocalToolOptions, E as ErrorEvent, l as ExchangeAuthorizationCodeOptions, L as LocalA2ATool, m as LocalHandlers, n as LocalMcpHttpTransport, o as LocalMcpServer, p as LocalMcpStdioTransport, q as LocalTool, r as LocalToolCallEvent, s as LocalToolResultInEvent, t as LoopDetectedEvent, u as LoopDetection, v as MantyxA2AOptions, w as MantyxAuthError, M as MantyxClient, x as MantyxClientOptions, y as MantyxError, z as MantyxMcpOptions, B as MantyxNetworkError, F as MantyxOAuthClient, G as MantyxOAuthClientOptions, H as MantyxOAuthError, I as MantyxParseError, J as MantyxPluginToolRef, K as MantyxRunError, N as MantyxRunErrorInit, O as MantyxScopeError, P as MantyxToolError, Q as MantyxToolRef, S as McpToolRef, U as ModelCatalog, V as ModelInfo, W as OAuthToken, X as OutputSchema, R as ReasoningLevel, Y as RefreshOptions, Z as RefreshTokenSourceOptions, _ as ResultEvent, $ as RevokeOptions, a0 as RunEvent, a1 as RunEventBase, a2 as RunResult, a3 as RunSpec, a4 as ServerToolResultEvent, a5 as SessionInfo, a6 as SessionSpec, a7 as ThinkingDeltaEvent, a8 as TokenRequestReason, a9 as TokenSource, aa as ToolBudget, ab as ToolBudgetExceededEvent, ac as ToolBudgets, T as ToolRef, ad as ZodLikeObject, ae as defineLocalA2A, af as defineLocalMcp, ag as defineLocalTool, ah as generatePkceVerifier, ai as isLocalA2ATool, aj as isLocalMcpServer, ak as isLocalTool, al as mantyxA2A, am as mantyxMcp, an as mantyxPluginTool, ao as mantyxTool, ap as parseRunOutput, aq as pkceChallenge } from './client-DHwh8MPj.js';
 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);
-}
-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);
-}
-/**
- * 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;
-    });
-}
-
 /**
  * Lightweight Zod → JSON Schema converter for tool parameter definitions.
  *
@@ -97,6 +52,6 @@ declare function readSseStream(body: ReadableStream<Uint8Array> | null, opts?: S
 /**
  * Release version — synced from repo root VERSION (`npm run sync-version`).
  */
-declare const SDK_VERSION = "0.9.0";
+declare const SDK_VERSION = "0.10.0";
 
-export { MantyxAuthError, MantyxError, MantyxNetworkError, MantyxParseError, MantyxRunError, MantyxToolError, SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };
+export { SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   MantyxNetworkError,
   MantyxParseError,
   MantyxRunError,
+  MantyxScopeError,
   MantyxToolError,
   defineLocalA2A,
   defineLocalMcp,
@@ -22,24 +23,307 @@ import {
   readSseStream,
   toToolParametersWire,
   zodToJsonSchema
-} from "./chunk-TYRJBHLM.js";
+} from "./chunk-XMUCELMH.js";
+
+// src/oauth.ts
+import { Buffer } from "buffer";
+import { createHash, randomBytes } from "crypto";
+var DEFAULT_OAUTH_BASE_URL = "https://app.mantyx.io";
+var DEFAULT_REFRESH_SKEW_MS = 6e4;
+var MantyxOAuthError = class extends MantyxError {
+  oauthError;
+  oauthErrorDescription;
+  constructor(oauthError, oauthErrorDescription, status) {
+    const message = oauthErrorDescription ? `OAuth ${oauthError}: ${oauthErrorDescription}` : `OAuth ${oauthError}`;
+    super(message, { code: oauthError, status });
+    this.name = "MantyxOAuthError";
+    this.oauthError = oauthError;
+    this.oauthErrorDescription = oauthErrorDescription;
+  }
+};
+var MantyxOAuthClient = class {
+  clientId;
+  baseUrl;
+  clientSecret;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.clientId) {
+      throw new MantyxError("`clientId` is required for MantyxOAuthClient");
+    }
+    if (!opts.clientSecret) {
+      throw new MantyxError("`clientSecret` is required for MantyxOAuthClient");
+    }
+    const f = opts.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new MantyxError(
+        "Global fetch is not available; pass a custom `fetch` implementation in MantyxOAuthClientOptions."
+      );
+    }
+    this.clientId = opts.clientId;
+    this.clientSecret = opts.clientSecret;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_OAUTH_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = f;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  /**
+   * 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".
+   */
+  async exchangeAuthorizationCode(opts) {
+    return this.token({
+      grant_type: "authorization_code",
+      code: opts.code,
+      redirect_uri: opts.redirectUri,
+      code_verifier: opts.codeVerifier
+    });
+  }
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  async refresh(opts) {
+    if (!opts.refreshToken) {
+      throw new MantyxError("`refreshToken` is required for MantyxOAuthClient.refresh");
+    }
+    const body = {
+      grant_type: "refresh_token",
+      refresh_token: opts.refreshToken
+    };
+    const scope = normalizeScope(opts.scope);
+    if (scope !== void 0) body.scope = scope;
+    return this.token(body);
+  }
+  /**
+   * 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.
+   */
+  async clientCredentials(opts = {}) {
+    const body = {
+      grant_type: "client_credentials"
+    };
+    const scope = normalizeScope(opts.scope);
+    if (scope !== void 0) body.scope = scope;
+    return this.token(body);
+  }
+  /**
+   * 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.
+   */
+  async revoke(opts) {
+    if (!opts.token) {
+      throw new MantyxError("`token` is required for MantyxOAuthClient.revoke");
+    }
+    await this.formPost("/api/oauth/revoke", {
+      token: opts.token
+    });
+  }
+  /**
+   * 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.
+   */
+  refreshTokenSource(opts) {
+    if (!opts.refreshToken) {
+      throw new MantyxError("`refreshToken` is required for MantyxOAuthClient.refreshTokenSource");
+    }
+    const skew = opts.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;
+    const cache = { token: opts.initialToken, inflight: null };
+    const refreshToken = opts.refreshToken;
+    return makeTokenSource(cache, skew, async () => {
+      return this.refresh({ refreshToken, scope: opts.scope });
+    });
+  }
+  /**
+   * 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 = {}) {
+    const skew = opts.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;
+    const cache = { token: void 0, inflight: null };
+    return makeTokenSource(cache, skew, async () => {
+      return this.clientCredentials({ scope: opts.scope });
+    });
+  }
+  // -------------------------------------------------------------- internals
+  /**
+   * 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.
+   */
+  async token(body) {
+    const res = await this.formPost("/api/oauth/token", body);
+    let parsed = {};
+    try {
+      parsed = await res.json();
+    } catch {
+      throw new MantyxOAuthError(
+        "invalid_response",
+        "Token endpoint returned a non-JSON response",
+        res.status
+      );
+    }
+    const accessToken = typeof parsed.access_token === "string" ? parsed.access_token : "";
+    if (!accessToken) {
+      throw new MantyxOAuthError(
+        "invalid_response",
+        "Token endpoint response is missing `access_token`",
+        res.status
+      );
+    }
+    const expiresIn = typeof parsed.expires_in === "number" ? parsed.expires_in : 3600;
+    return {
+      accessToken,
+      refreshToken: typeof parsed.refresh_token === "string" ? parsed.refresh_token : void 0,
+      tokenType: typeof parsed.token_type === "string" ? parsed.token_type : "Bearer",
+      expiresIn,
+      expiresAt: Date.now() + expiresIn * 1e3,
+      scope: typeof parsed.scope === "string" ? parsed.scope : void 0
+    };
+  }
+  async formPost(path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const params = new URLSearchParams({
+      ...body,
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    });
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json"
+        },
+        body: params.toString(),
+        signal: ctrl.signal
+      });
+    } catch (err) {
+      if (ctrl.signal.aborted) {
+        throw new MantyxNetworkError(`OAuth request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new MantyxNetworkError(`OAuth network error: ${err.message}`, {
+        cause: err
+      });
+    } finally {
+      clearTimeout(t);
+    }
+    if (!res.ok) {
+      let errBody = {};
+      try {
+        errBody = await res.json();
+      } catch {
+      }
+      const oauthError = typeof errBody.error === "string" ? errBody.error : `http_${res.status}`;
+      const desc = typeof errBody.error_description === "string" ? errBody.error_description : void 0;
+      throw new MantyxOAuthError(oauthError, desc, res.status);
+    }
+    return res;
+  }
+};
+function generatePkceVerifier(length = 64) {
+  if (length < 43 || length > 128) {
+    throw new MantyxError("PKCE code_verifier length must be in [43, 128]");
+  }
+  const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+  const bytes = randomBytes(length);
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += ALPHABET[bytes[i] % ALPHABET.length];
+  }
+  return out;
+}
+function pkceChallenge(verifier) {
+  const hash = createHash("sha256").update(verifier, "utf8").digest();
+  return Buffer.from(hash).toString("base64").replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function makeTokenSource(cache, skewMs, mint) {
+  return async (reason = "initial") => {
+    if (reason !== "unauthorized" && cache.token && !isExpiring(cache.token, skewMs)) {
+      return cache.token.accessToken;
+    }
+    if (cache.inflight) {
+      const t = await cache.inflight;
+      if (reason === "unauthorized" && t === cache.token) {
+      } else {
+        return t.accessToken;
+      }
+    }
+    cache.inflight = mint().then(
+      (t) => {
+        cache.token = t;
+        return t;
+      },
+      (err) => {
+        throw err;
+      }
+    );
+    try {
+      const t = await cache.inflight;
+      return t.accessToken;
+    } finally {
+      cache.inflight = null;
+    }
+  };
+}
+function isExpiring(token, skewMs) {
+  return token.expiresAt - Date.now() <= skewMs;
+}
+function normalizeScope(scope) {
+  if (scope === void 0) return void 0;
+  if (typeof scope === "string") {
+    const trimmed = scope.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  const joined = scope.filter((s) => typeof s === "string" && s.length > 0).join(" ");
+  return joined.length > 0 ? joined : void 0;
+}
 
 // src/version.ts
-var SDK_VERSION = "0.9.0";
+var SDK_VERSION = "0.10.0";
 export {
   AgentSession,
   DEFAULT_BASE_URL,
+  DEFAULT_OAUTH_BASE_URL,
+  DEFAULT_REFRESH_SKEW_MS,
   MantyxAuthError,
   MantyxClient,
   MantyxError,
   MantyxNetworkError,
+  MantyxOAuthClient,
+  MantyxOAuthError,
   MantyxParseError,
   MantyxRunError,
+  MantyxScopeError,
   MantyxToolError,
   SDK_VERSION,
   defineLocalA2A,
   defineLocalMcp,
   defineLocalTool,
+  generatePkceVerifier,
   isLocalA2ATool,
   isLocalMcpServer,
   isLocalTool,
@@ -48,6 +332,7 @@ export {
   mantyxPluginTool,
   mantyxTool,
   parseRunOutput,
+  pkceChallenge,
   readSseStream,
   toToolParametersWire,
   zodToJsonSchema

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["/**\n * Release version — synced from repo root VERSION (`npm run sync-version`).\n */\nexport const SDK_VERSION = \"0.9.0\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAGO,IAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/oauth.ts","../src/version.ts"],"sourcesContent":["/**\n * MANTYX OAuth 2.0 client: authorization-code exchange, refresh-token\n * minting, client-credentials grant, and token revocation, plus typed\n * {@link TokenSource}s that {@link MantyxClient} can consume to refresh\n * access tokens transparently before they expire (and again on 401).\n *\n * The wire contract this implements is `docs/oauth.md` in the SDK monorepo:\n *\n * - Token endpoint: `POST <baseUrl>/api/oauth/token`, form-encoded.\n * - Revoke endpoint: `POST <baseUrl>/api/oauth/revoke`, form-encoded.\n * - Access tokens (`mantyx_at_…`) live 1 hour (`expires_in: 3600`).\n * - Refresh tokens (`mantyx_rt_…`) are **persistent and non-rotating**:\n *   `grant_type=refresh_token` echoes back the same value the client\n *   sent. The caller persists the refresh token once at first sign-in\n *   (encrypted at rest) and the SDK re-mints access tokens from it on\n *   demand.\n *\n * See also `docs/oauth.md` for the authorization-code + PKCE consent\n * flow (which the SDK does **not** drive — the calling app owns the\n * redirect dance; once it has the auth code, `exchangeAuthorizationCode`\n * swaps it for the initial `{access_token, refresh_token}` pair).\n */\n\nimport { Buffer } from \"node:buffer\";\nimport { createHash, randomBytes } from \"node:crypto\";\n\nimport { MantyxError, MantyxNetworkError } from \"./errors.js\";\n\nexport const DEFAULT_OAUTH_BASE_URL = \"https://app.mantyx.io\";\n\n/** Skew (ms) before `expiresAt` at which a TokenSource will pre-emptively refresh. Default 60s. */\nexport const DEFAULT_REFRESH_SKEW_MS = 60_000;\n\n/**\n * Raised on a non-2xx response from `POST /api/oauth/token` or\n * `POST /api/oauth/revoke`. Carries the RFC 6749 `error` discriminator\n * (`\"invalid_grant\"`, `\"invalid_client\"`, `\"unsupported_grant_type\"`,\n * …) and the optional `error_description` so callers can branch on\n * machine-readable values without parsing the human message.\n *\n * `invalid_grant` from the refresh path specifically signals that the\n * refresh token has been revoked (or the OAuth grant / application\n * was deleted). The SDK never loops on this — callers should route\n * the user back to a fresh sign-in.\n */\nexport class MantyxOAuthError extends MantyxError {\n  readonly oauthError: string;\n  readonly oauthErrorDescription: string | undefined;\n\n  constructor(\n    oauthError: string,\n    oauthErrorDescription: string | undefined,\n    status: number,\n  ) {\n    const message = oauthErrorDescription\n      ? `OAuth ${oauthError}: ${oauthErrorDescription}`\n      : `OAuth ${oauthError}`;\n    super(message, { code: oauthError, status });\n    this.name = \"MantyxOAuthError\";\n    this.oauthError = oauthError;\n    this.oauthErrorDescription = oauthErrorDescription;\n  }\n}\n\n/**\n * Decoded `POST /api/oauth/token` response, augmented with an absolute\n * `expiresAt` timestamp the SDK can use to decide when to refresh.\n *\n * `refreshToken` is present on the initial `authorization_code` exchange\n * and on subsequent `refresh_token` calls (where it is identical to the\n * value the client just sent — refresh tokens never rotate). The\n * `client_credentials` grant never returns one.\n */\nexport interface OAuthToken {\n  readonly accessToken: string;\n  readonly refreshToken: string | undefined;\n  readonly tokenType: string;\n  readonly expiresIn: number;\n  /** Absolute Unix-ms timestamp set when the SDK parsed the response. */\n  readonly expiresAt: number;\n  readonly scope: string | undefined;\n}\n\n/** Why the SDK asked the {@link TokenSource} for the current access token. */\nexport type TokenRequestReason = \"initial\" | \"expired\" | \"unauthorized\";\n\n/**\n * A `TokenSource` produces the current access token on demand. The\n * {@link MantyxClient} HTTP layer calls it before every request. When\n * called with `reason: \"unauthorized\"` the source MUST force a refresh\n * (do not return a cached value); this is how the SDK recovers from\n * 401s caused by a token that the server already invalidated.\n *\n * Implementations should be safe to call from many concurrent requests.\n */\nexport type TokenSource = (reason?: TokenRequestReason) => Promise<string>;\n\n/** Caller-supplied options for `MantyxOAuthClient`. */\nexport interface MantyxOAuthClientOptions {\n  /**\n   * OAuth `client_id` issued at app registration (token prefix\n   * `mantyx_oa_`).\n   */\n  clientId: string;\n  /**\n   * OAuth `client_secret` issued at app registration (token prefix\n   * `mantyx_oas_`). Every MANTYX OAuth app is a confidential client,\n   * so this is always required for token + revoke calls. Treat as a\n   * deployment secret — do not bundle into browser builds.\n   */\n  clientSecret: string;\n  /**\n   * Origin of the MANTYX deployment. Defaults to `https://app.mantyx.io`.\n   * The OAuth endpoints are mounted at `<baseUrl>/api/oauth/...`.\n   */\n  baseUrl?: string;\n  /** Optional `fetch` override (e.g. node-fetch wrapper). Default: global `fetch`. */\n  fetch?: typeof fetch;\n  /** Default per-request timeout in milliseconds. Default: 30s. */\n  timeoutMs?: number;\n}\n\nexport interface ExchangeAuthorizationCodeOptions {\n  code: string;\n  redirectUri: string;\n  codeVerifier: string;\n}\n\nexport interface RefreshOptions {\n  refreshToken: string;\n  /**\n   * Optional scope narrowing. Must be a subset of the scopes already\n   * granted to the refresh token (server enforces this). Useful when\n   * an SDK consumer wants a short-scope access token for a specific\n   * sub-operation.\n   */\n  scope?: string | readonly string[];\n}\n\nexport interface ClientCredentialsOptions {\n  scope?: string | readonly string[];\n}\n\nexport interface RevokeOptions {\n  token: string;\n}\n\nexport interface RefreshTokenSourceOptions {\n  refreshToken: string;\n  /** Optional scope narrowing applied on every refresh. */\n  scope?: string | readonly string[];\n  /**\n   * How many ms before `expiresAt` the source proactively refreshes.\n   * Defaults to {@link DEFAULT_REFRESH_SKEW_MS} (60s).\n   */\n  refreshSkewMs?: number;\n  /**\n   * Optional initial access token + expiry to seed the source's cache\n   * with (e.g. the token already in hand from the authorization-code\n   * exchange). When omitted, the source mints one on the first call.\n   */\n  initialToken?: OAuthToken;\n}\n\nexport interface ClientCredentialsTokenSourceOptions {\n  scope?: string | readonly string[];\n  refreshSkewMs?: number;\n}\n\n/**\n * Wraps the MANTYX OAuth 2.0 authorization-server endpoints. App-scoped\n * (one per `{clientId, clientSecret}` pair); construct independently of\n * {@link MantyxClient}, then either call its grant helpers directly or\n * hand a `TokenSource` it produces to `MantyxClient` for fully\n * transparent refresh.\n */\nexport class MantyxOAuthClient {\n  readonly clientId: string;\n  readonly baseUrl: string;\n  private readonly clientSecret: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly timeoutMs: number;\n\n  constructor(opts: MantyxOAuthClientOptions) {\n    if (!opts.clientId) {\n      throw new MantyxError(\"`clientId` is required for MantyxOAuthClient\");\n    }\n    if (!opts.clientSecret) {\n      throw new MantyxError(\"`clientSecret` is required for MantyxOAuthClient\");\n    }\n    const f = opts.fetch ?? globalThis.fetch;\n    if (typeof f !== \"function\") {\n      throw new MantyxError(\n        \"Global fetch is not available; pass a custom `fetch` implementation in MantyxOAuthClientOptions.\",\n      );\n    }\n    this.clientId = opts.clientId;\n    this.clientSecret = opts.clientSecret;\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_OAUTH_BASE_URL).replace(/\\/+$/, \"\");\n    this.fetchImpl = f;\n    this.timeoutMs = opts.timeoutMs ?? 30_000;\n  }\n\n  /**\n   * Swap an authorization-code + PKCE verifier for the initial\n   * `{access_token, refresh_token}` pair. Call this exactly once per\n   * sign-in after the browser/native redirect lands back on your\n   * `redirectUri` with a `code` parameter. Persist the returned\n   * `refreshToken` against the user record — it is long-lived and\n   * non-rotating per `docs/oauth.md` §\"Token lifetimes & lifecycle\".\n   */\n  async exchangeAuthorizationCode(opts: ExchangeAuthorizationCodeOptions): Promise<OAuthToken> {\n    return this.token({\n      grant_type: \"authorization_code\",\n      code: opts.code,\n      redirect_uri: opts.redirectUri,\n      code_verifier: opts.codeVerifier,\n    });\n  }\n\n  /**\n   * Mint a fresh access token from a stored refresh token. The\n   * returned `refreshToken` is identical to the input — the field is\n   * surfaced for symmetry with {@link exchangeAuthorizationCode} only.\n   *\n   * On `400 invalid_grant` the refresh token has been revoked (or its\n   * grant / app was deleted); the SDK surfaces a\n   * {@link MantyxOAuthError} and callers must drive a fresh sign-in.\n   */\n  async refresh(opts: RefreshOptions): Promise<OAuthToken> {\n    if (!opts.refreshToken) {\n      throw new MantyxError(\"`refreshToken` is required for MantyxOAuthClient.refresh\");\n    }\n    const body: Record<string, string> = {\n      grant_type: \"refresh_token\",\n      refresh_token: opts.refreshToken,\n    };\n    const scope = normalizeScope(opts.scope);\n    if (scope !== undefined) body.scope = scope;\n    return this.token(body);\n  }\n\n  /**\n   * Request a workspace-scoped access token without a user via the\n   * `client_credentials` grant. Available only on private OAuth apps\n   * that were registered with `allowsClientCredentials: true`. No\n   * refresh token is issued; re-call this method whenever a new\n   * access token is needed.\n   */\n  async clientCredentials(opts: ClientCredentialsOptions = {}): Promise<OAuthToken> {\n    const body: Record<string, string> = {\n      grant_type: \"client_credentials\",\n    };\n    const scope = normalizeScope(opts.scope);\n    if (scope !== undefined) body.scope = scope;\n    return this.token(body);\n  }\n\n  /**\n   * Revoke an access or refresh token (RFC 7009). The server always\n   * returns 200, even for unknown tokens. Revoking a **refresh**\n   * token kills the refresh and every live access token tied to its\n   * grant; revoking an **access** token kills only that one.\n   */\n  async revoke(opts: RevokeOptions): Promise<void> {\n    if (!opts.token) {\n      throw new MantyxError(\"`token` is required for MantyxOAuthClient.revoke\");\n    }\n    await this.formPost(\"/api/oauth/revoke\", {\n      token: opts.token,\n    });\n  }\n\n  /**\n   * Build a long-lived {@link TokenSource} that re-mints access\n   * tokens from the supplied refresh token. Pass the returned source\n   * to `new MantyxClient({ tokenSource, workspaceSlug, ... })`. The\n   * source caches the access token in-memory and refreshes\n   * proactively when the cached value is within `refreshSkewMs` of\n   * `expiresAt`, or eagerly when `MantyxClient` reports a 401.\n   */\n  refreshTokenSource(opts: RefreshTokenSourceOptions): TokenSource {\n    if (!opts.refreshToken) {\n      throw new MantyxError(\"`refreshToken` is required for MantyxOAuthClient.refreshTokenSource\");\n    }\n    const skew = opts.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;\n    const cache: TokenCache = { token: opts.initialToken, inflight: null };\n    const refreshToken = opts.refreshToken;\n    return makeTokenSource(cache, skew, async () => {\n      return this.refresh({ refreshToken, scope: opts.scope });\n    });\n  }\n\n  /**\n   * Build a long-lived {@link TokenSource} backed by the\n   * `client_credentials` grant. On every refresh the source re-mints\n   * a workspace-scoped access token by calling the token endpoint\n   * with `grant_type=client_credentials`. Available only on private\n   * apps with `allowsClientCredentials: true`.\n   */\n  clientCredentialsTokenSource(opts: ClientCredentialsTokenSourceOptions = {}): TokenSource {\n    const skew = opts.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;\n    const cache: TokenCache = { token: undefined, inflight: null };\n    return makeTokenSource(cache, skew, async () => {\n      return this.clientCredentials({ scope: opts.scope });\n    });\n  }\n\n  // -------------------------------------------------------------- internals\n\n  /**\n   * POST `application/x-www-form-urlencoded` to `/api/oauth/token` and\n   * decode the {@link OAuthToken} response. Always injects `client_id`\n   * + `client_secret` from the constructor.\n   */\n  private async token(body: Record<string, string>): Promise<OAuthToken> {\n    const res = await this.formPost(\"/api/oauth/token\", body);\n    let parsed: Record<string, unknown> = {};\n    try {\n      parsed = (await res.json()) as Record<string, unknown>;\n    } catch {\n      throw new MantyxOAuthError(\n        \"invalid_response\",\n        \"Token endpoint returned a non-JSON response\",\n        res.status,\n      );\n    }\n    const accessToken = typeof parsed.access_token === \"string\" ? parsed.access_token : \"\";\n    if (!accessToken) {\n      throw new MantyxOAuthError(\n        \"invalid_response\",\n        \"Token endpoint response is missing `access_token`\",\n        res.status,\n      );\n    }\n    const expiresIn = typeof parsed.expires_in === \"number\" ? parsed.expires_in : 3600;\n    return {\n      accessToken,\n      refreshToken: typeof parsed.refresh_token === \"string\" ? parsed.refresh_token : undefined,\n      tokenType: typeof parsed.token_type === \"string\" ? parsed.token_type : \"Bearer\",\n      expiresIn,\n      expiresAt: Date.now() + expiresIn * 1000,\n      scope: typeof parsed.scope === \"string\" ? parsed.scope : undefined,\n    };\n  }\n\n  private async formPost(path: string, body: Record<string, string>): Promise<Response> {\n    const url = `${this.baseUrl}${path}`;\n    const params = new URLSearchParams({\n      ...body,\n      client_id: this.clientId,\n      client_secret: this.clientSecret,\n    });\n    const ctrl = new AbortController();\n    const t = setTimeout(() => ctrl.abort(), this.timeoutMs);\n    let res: Response;\n    try {\n      res = await this.fetchImpl(url, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/x-www-form-urlencoded\",\n          Accept: \"application/json\",\n        },\n        body: params.toString(),\n        signal: ctrl.signal,\n      });\n    } catch (err) {\n      if (ctrl.signal.aborted) {\n        throw new MantyxNetworkError(`OAuth request timed out after ${this.timeoutMs}ms`);\n      }\n      throw new MantyxNetworkError(`OAuth network error: ${(err as Error).message}`, {\n        cause: err,\n      });\n    } finally {\n      clearTimeout(t);\n    }\n    if (!res.ok) {\n      let errBody: { error?: unknown; error_description?: unknown } = {};\n      try {\n        errBody = (await res.json()) as typeof errBody;\n      } catch {\n        // ignore\n      }\n      const oauthError = typeof errBody.error === \"string\" ? errBody.error : `http_${res.status}`;\n      const desc =\n        typeof errBody.error_description === \"string\" ? errBody.error_description : undefined;\n      throw new MantyxOAuthError(oauthError, desc, res.status);\n    }\n    return res;\n  }\n}\n\n// -------------------------------------------------------------- PKCE helpers\n\n/**\n * Generate a high-entropy PKCE `code_verifier` (RFC 7636 §4.1). The\n * verifier is the raw secret you keep across the redirect; the\n * `code_challenge` you send on `/api/oauth/authorize` is derived from\n * it via {@link pkceChallenge}.\n *\n * Default length is 64 characters (≈ 384 bits of entropy after\n * base64url-encoding the 32 random bytes). Pass `length` to clamp to\n * the RFC's 43..128 inclusive range.\n */\nexport function generatePkceVerifier(length = 64): string {\n  if (length < 43 || length > 128) {\n    throw new MantyxError(\"PKCE code_verifier length must be in [43, 128]\");\n  }\n  // 32 random bytes -> 43 base64url chars; we then slice / pad up to the\n  // requested length using the unreserved RFC 7636 alphabet.\n  const ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~\";\n  const bytes = randomBytes(length);\n  let out = \"\";\n  for (let i = 0; i < length; i++) {\n    out += ALPHABET[bytes[i]! % ALPHABET.length];\n  }\n  return out;\n}\n\n/**\n * Compute the PKCE `S256` `code_challenge` for a given verifier:\n * `base64url(sha256(verifier))` with no padding (RFC 7636 §4.2).\n */\nexport function pkceChallenge(verifier: string): string {\n  const hash = createHash(\"sha256\").update(verifier, \"utf8\").digest();\n  return Buffer.from(hash)\n    .toString(\"base64\")\n    .replace(/=+$/, \"\")\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\");\n}\n\n// -------------------------------------------------------------- internals\n\ninterface TokenCache {\n  token: OAuthToken | undefined;\n  inflight: Promise<OAuthToken> | null;\n}\n\n/**\n * Wrap a `mintToken` thunk into a single-flight {@link TokenSource}\n * with a cache + proactive-refresh skew. The cache is overwritten\n * atomically on every successful mint; the in-flight promise\n * collapses N concurrent expired-token observers into one mint call.\n *\n * Single-flight is an efficiency, not a correctness requirement —\n * `docs/oauth.md` explicitly allows multiple concurrent refreshes\n * against the same refresh token — but it keeps the token-endpoint\n * QPS reasonable when an SDK consumer fans out work in parallel.\n */\nfunction makeTokenSource(\n  cache: TokenCache,\n  skewMs: number,\n  mint: () => Promise<OAuthToken>,\n): TokenSource {\n  return async (reason: TokenRequestReason = \"initial\"): Promise<string> => {\n    if (reason !== \"unauthorized\" && cache.token && !isExpiring(cache.token, skewMs)) {\n      return cache.token.accessToken;\n    }\n    if (cache.inflight) {\n      const t = await cache.inflight;\n      // If the inflight refresh was triggered by a benign cache miss\n      // and we observed an unauthorized hint after it started, retry\n      // once with a forced mint so the caller never gets a stale token.\n      if (reason === \"unauthorized\" && t === cache.token) {\n        // fallthrough to fresh mint below\n      } else {\n        return t.accessToken;\n      }\n    }\n    cache.inflight = mint().then(\n      (t) => {\n        cache.token = t;\n        return t;\n      },\n      (err: unknown) => {\n        throw err;\n      },\n    );\n    try {\n      const t = await cache.inflight;\n      return t.accessToken;\n    } finally {\n      cache.inflight = null;\n    }\n  };\n}\n\nfunction isExpiring(token: OAuthToken, skewMs: number): boolean {\n  return token.expiresAt - Date.now() <= skewMs;\n}\n\nfunction normalizeScope(scope: string | readonly string[] | undefined): string | undefined {\n  if (scope === undefined) return undefined;\n  if (typeof scope === \"string\") {\n    const trimmed = scope.trim();\n    return trimmed.length > 0 ? trimmed : undefined;\n  }\n  const joined = scope.filter((s) => typeof s === \"string\" && s.length > 0).join(\" \");\n  return joined.length > 0 ? joined : undefined;\n}\n","/**\n * Release version — synced from repo root VERSION (`npm run sync-version`).\n */\nexport const SDK_VERSION = \"0.10.0\";\n"],"mappings":"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","names":[]}

package/docs/agent-runs-protocol.md

@@ -66,17 +66,124 @@ All SDK-facing endpoints sit under
 /api/v1/workspaces/{workspaceSlug}/...
 ```
 
-and are authenticated with a workspace API key with usage `developer_api`:
+and accept **either** of two bearer credentials interchangeably. The same
+header carries either, so SDKs only need one code path:
 
 ```
-Authorization: Bearer <api-key>
+Authorization: Bearer <credential>
 # or, equivalently:
-X-API-Key: <api-key>
+X-API-Key: <credential>
 ```
 
-The workspace slug in the URL must match the key's tenant. Mismatches return
-`404 not_found`. Missing/invalid keys return `401 unauthorized`. Rate limits
-follow the workspace's existing developer-API sliding-window policy.
+| Credential                | Token format    | Identifies               | Bound to                | Use when |
+| ------------------------- | --------------- | ------------------------ | ----------------------- | -------- |
+| **Workspace API key**     | `mantyx_…`      | The workspace            | One workspace, no end-user | Personal scripts, internal automations, anything the SDK caller owns end-to-end. |
+| **OAuth 2.0 access token**| `mantyx_at_…`   | An end user **and** the workspace they consented for | One workspace, one user (or one app for `client_credentials`) | "Sign in with MANTYX" apps, third-party integrations, anywhere consent + scopes matter. |
+
+The server resolves whichever it sees by token-prefix sniffing (see
+`packages/api/src/services/bearer-credential.ts`) — SDKs do **not** need
+separate code paths or env variables for the two flavours.
+
+The workspace slug in the URL must match the credential's tenant.
+Mismatches return `404 not_found` with a `hint` field pointing at the
+correct slug. Missing/invalid credentials return `401 unauthorized`.
+Rate limits follow the workspace's existing developer-API sliding-window
+policy and are tracked per-credential.
+
+### 2.1 Workspace API keys (machine credentials)
+
+A workspace admin issues an API key under **Settings → API keys** with
+**Usage = Developer API**. The key inherits two optional restrictions:
+
+- **Agent allowlist** (`ApiKey.agentIds`) — empty list = "every
+  non-system agent in the workspace"; otherwise only the listed agents
+  are visible to `spec.agentId` and ephemeral runs created from the key.
+- **Plan gate** — the workspace tier must include the `apiKeys` feature.
+
+API keys carry no granular scopes; possession of a Developer-API key is
+enough to call every route in this document.
+
+### 2.2 OAuth 2.0 access tokens
+
+OAuth tokens are a drop-in alternative for the same set of routes, with
+two differences:
+
+1. **Scopes are required.** Each route checks the token carries the
+   right scope via `requireScope(...)` and returns
+   `403 { "error": "insufficient_scope", "required": "runs:write" }`
+   (the value is a string for single-scope routes, an array for
+   multi-scope ones — see §2.3). The SDK is expected to surface this
+   verbatim. The agent-runs surface uses these scopes:
+
+   | Endpoint                                                     | Required scope |
+   | ------------------------------------------------------------ | -------------- |
+   | `GET    .../models`                                          | `models:read` |
+   | `POST   .../agent-runs`                                      | `runs:write` |
+   | `GET    .../agent-runs/{runId}`                              | `runs:read` |
+   | `GET    .../agent-runs/{runId}/stream`                       | `runs:read` |
+   | `POST   .../agent-runs/{runId}/cancel`                       | `runs:write` |
+   | `POST   .../agent-runs/{runId}/tool-results`                 | `runs:write` |
+   | `POST   .../agent-sessions`                                  | `sessions:write` |
+   | `GET    .../agent-sessions/{sessionId}`                      | `sessions:read` |
+   | `DELETE .../agent-sessions/{sessionId}`                      | `sessions:write` |
+   | `POST   .../agent-sessions/{sessionId}/messages`             | `sessions:write` |
+   | `GET    /api/oauth/userinfo`                                 | `mantyx.identity:read` |
+
+   For an SDK that exposes one-shot runs and sessions end-to-end, request
+   at minimum `models:read runs:read runs:write sessions:read sessions:write`,
+   and add `mantyx.identity:read` if the SDK calls
+   `/api/oauth/userinfo` to discover the workspace slug after sign-in.
+
+2. **Tokens are workspace-scoped.** An access token is minted for one
+   workspace (chosen by the user at consent time for public apps, or the
+   registering workspace for private apps). Calling
+   `/api/v1/workspaces/{otherSlug}/...` with such a token returns
+   `404 not_found` plus a `hint` with the correct slug.
+
+OAuth tokens **also** honor the per-token agent allow-list
+(`OAuthAccessToken.agentIds`) the user picked at consent time — see
+[`docs/oauth.md`](./oauth.md) for the full registration / authorization-code
++ PKCE flow. PKCE (`S256`) is mandatory and every MANTYX OAuth app is a
+confidential client, so the token endpoint requires both `client_secret`
+and `code_verifier`.
+
+**Token lifetimes.** Access tokens live **1 hour** (`expires_in: 3600`).
+Refresh tokens are **persistent and non-rotating**: they have no
+time-based expiry and `grant_type=refresh_token` returns the **same**
+refresh token the SDK already holds while minting a brand-new short-lived
+access token. Multiple processes may refresh concurrently using the same
+refresh token without invalidating each other. Refresh tokens stop
+working only when the application access is revoked (`/oauth/revoke`,
+`DELETE /api/oauth/grants/:id`, or app deletion).
+
+> **SDK guidance.** Persist the refresh token at first sign-in, treat it
+> as long-lived, and keep refreshing the access token off it on demand
+> (e.g. ~5 minutes before `expires_in` runs out, or lazily on the first
+> `401`). Do **not** rotate or replace the refresh token after each
+> refresh — the value is stable.
+
+A single SDK call site looks identical regardless of credential:
+
+```http
+POST /api/v1/workspaces/acme/agent-runs HTTP/1.1
+Authorization: Bearer mantyx_at_…   # OAuth access token
+# — or —
+Authorization: Bearer mantyx_…      # workspace API key
+Content-Type: application/json
+
+{ "modelId": "openai:gpt-5.5", "prompt": "...", "tools": [...] }
+```
+
+### 2.3 Error model for credentials
+
+| Status | Body shape                                                                            | When |
+| ------ | ------------------------------------------------------------------------------------- | ---- |
+| `401`  | `{ "error": "Unauthorized", "message": "API key or OAuth access token required..." }` | No `Authorization` / `X-API-Key` header. |
+| `401`  | `{ "error": "Invalid API key or OAuth access token" }`                                | Token doesn't match a row, expired, or revoked. |
+| `403`  | `{ "error": "This API key is not for the Developer API", "hint": "..." }`             | API key has wrong `usage`. |
+| `403`  | `{ "error": "Workspace API keys are not available on this plan.", "code": "api_keys_plan" }` <br> `{ "error": "OAuth applications are not available on this plan.", "code": "oauth_apps_plan" }` | Workspace tier lacks the `apiKeys` / `oauthApps` feature. |
+| `403`  | `{ "error": "insufficient_scope", "required": "runs:write" }` (or an array if a route needs multiple) | OAuth token is missing a scope a route demands. The response also sets `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. |
+| `404`  | `{ "error": "Workspace path does not match this credential", "hint": "..." }`         | URL slug ≠ token's workspace. |
 
 ## 3. Models