@mantyx/sdk 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-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 DEFAULT_OAUTH_BASE_URL, f as DEFAULT_REFRESH_SKEW_MS, g as DefineLocalA2AOptions, h as DefineLocalMcpOptions, i as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, j as LocalHandlers, k as LocalMcpHttpTransport, l as LocalMcpServer, m as LocalMcpStdioTransport, n as LocalTool, o as LocalToolCallEvent, p as LocalToolResultInEvent, q as LoopDetectedEvent, r as LoopDetection, s as MantyxA2AOptions, t as MantyxAuthError, M as MantyxClient, u as MantyxClientOptions, v as MantyxError, w as MantyxMcpOptions, x as MantyxNetworkError, y as MantyxOAuthClient, z as MantyxOAuthClientOptions, B as MantyxOAuthError, F as MantyxParseError, G as MantyxPluginToolRef, H as MantyxRunError, I as MantyxRunErrorInit, J as MantyxRunErrorModel, K as MantyxRunErrorTokens, N as MantyxScopeError, O as MantyxToolError, P as MantyxToolRef, Q as McpToolRef, S as ModelCatalog, U as ModelInfo, V as OAuthToken, W as OutputSchema, R as ReasoningLevel, X as RefreshOptions, Y as RefreshTokenSourceOptions, Z as ResultEvent, _ as RevokeOptions, $ as RunEvent, a0 as RunEventBase, a1 as RunModelInfo, a2 as RunResult, a3 as RunSpec, a4 as RunTokenUsage, a5 as ServerToolResultEvent, a6 as SessionInfo, a7 as SessionSpec, a8 as ThinkingDeltaEvent, a9 as TokenRequestReason, aa as TokenSource, ab as ToolBudget, ac as ToolBudgetExceededEvent, ad as ToolBudgets, T as ToolRef, ae as ZodLikeObject, af as defineLocalA2A, ag as defineLocalMcp, ah as defineLocalTool, ai as isLocalA2ATool, aj as isLocalMcpServer, ak as isLocalTool, al as mantyxA2A, am as mantyxMcp, an as mantyxPluginTool, ao as mantyxTool, ap as parseRunOutput } from './client-Byb0Zdo7.cjs';
+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 DEFAULT_OAUTH_BASE_URL, f as DEFAULT_REFRESH_SKEW_MS, g as DefineLocalA2AOptions, h as DefineLocalMcpOptions, i as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, j as LocalHandlers, k as LocalMcpHttpTransport, l as LocalMcpServer, m as LocalMcpStdioTransport, n as LocalTool, o as LocalToolCallEvent, p as LocalToolResultInEvent, q as LoopDetectedEvent, r as LoopDetection, s as MantyxA2AOptions, t as MantyxAuthError, M as MantyxClient, u as MantyxClientOptions, v as MantyxError, w as MantyxMcpOptions, x as MantyxNetworkError, y as MantyxOAuthClient, z as MantyxOAuthClientOptions, B as MantyxOAuthError, F as MantyxParseError, G as MantyxPluginToolRef, H as MantyxRunError, I as MantyxRunErrorInit, J as MantyxRunErrorModel, K as MantyxRunErrorTokens, N as MantyxScopeError, O as MantyxToolError, P as MantyxToolRef, Q as McpToolRef, S as ModelCatalog, U as ModelInfo, V as OAuthToken, W as OutputSchema, R as ReasoningLevel, X as RefreshOptions, Y as RefreshTokenSourceOptions, Z as ResultEvent, _ as RevokeOptions, $ as RunEvent, a0 as RunEventBase, a1 as RunModelInfo, a2 as RunResult, a3 as RunSpec, a4 as RunTokenUsage, a5 as ServerToolResultEvent, a6 as SessionInfo, a7 as SessionSpec, a8 as Supervisor, a9 as SupervisorAction, aa as SupervisorEvent, ab as ThinkingDeltaEvent, ac as TokenRequestReason, ad as TokenSource, ae as ToolBudget, af as ToolBudgetExceededEvent, ag as ToolBudgets, T as ToolRef, ah as ZodLikeObject, ai as defineLocalA2A, aj as defineLocalMcp, ak as defineLocalTool, al as isLocalA2ATool, am as isLocalMcpServer, an as isLocalTool, ao as mantyxA2A, ap as mantyxMcp, aq as mantyxPluginTool, ar as mantyxTool, as as parseRunOutput } from './client-LQlx7iYY.cjs';
 import { z } from 'zod';
 
 /**
@@ -52,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.11.0";
+declare const SDK_VERSION = "0.12.0";
 
 export { SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 DEFAULT_OAUTH_BASE_URL, f as DEFAULT_REFRESH_SKEW_MS, g as DefineLocalA2AOptions, h as DefineLocalMcpOptions, i as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, j as LocalHandlers, k as LocalMcpHttpTransport, l as LocalMcpServer, m as LocalMcpStdioTransport, n as LocalTool, o as LocalToolCallEvent, p as LocalToolResultInEvent, q as LoopDetectedEvent, r as LoopDetection, s as MantyxA2AOptions, t as MantyxAuthError, M as MantyxClient, u as MantyxClientOptions, v as MantyxError, w as MantyxMcpOptions, x as MantyxNetworkError, y as MantyxOAuthClient, z as MantyxOAuthClientOptions, B as MantyxOAuthError, F as MantyxParseError, G as MantyxPluginToolRef, H as MantyxRunError, I as MantyxRunErrorInit, J as MantyxRunErrorModel, K as MantyxRunErrorTokens, N as MantyxScopeError, O as MantyxToolError, P as MantyxToolRef, Q as McpToolRef, S as ModelCatalog, U as ModelInfo, V as OAuthToken, W as OutputSchema, R as ReasoningLevel, X as RefreshOptions, Y as RefreshTokenSourceOptions, Z as ResultEvent, _ as RevokeOptions, $ as RunEvent, a0 as RunEventBase, a1 as RunModelInfo, a2 as RunResult, a3 as RunSpec, a4 as RunTokenUsage, a5 as ServerToolResultEvent, a6 as SessionInfo, a7 as SessionSpec, a8 as ThinkingDeltaEvent, a9 as TokenRequestReason, aa as TokenSource, ab as ToolBudget, ac as ToolBudgetExceededEvent, ad as ToolBudgets, T as ToolRef, ae as ZodLikeObject, af as defineLocalA2A, ag as defineLocalMcp, ah as defineLocalTool, ai as isLocalA2ATool, aj as isLocalMcpServer, ak as isLocalTool, al as mantyxA2A, am as mantyxMcp, an as mantyxPluginTool, ao as mantyxTool, ap as parseRunOutput } from './client-Byb0Zdo7.js';
+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 DEFAULT_OAUTH_BASE_URL, f as DEFAULT_REFRESH_SKEW_MS, g as DefineLocalA2AOptions, h as DefineLocalMcpOptions, i as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, j as LocalHandlers, k as LocalMcpHttpTransport, l as LocalMcpServer, m as LocalMcpStdioTransport, n as LocalTool, o as LocalToolCallEvent, p as LocalToolResultInEvent, q as LoopDetectedEvent, r as LoopDetection, s as MantyxA2AOptions, t as MantyxAuthError, M as MantyxClient, u as MantyxClientOptions, v as MantyxError, w as MantyxMcpOptions, x as MantyxNetworkError, y as MantyxOAuthClient, z as MantyxOAuthClientOptions, B as MantyxOAuthError, F as MantyxParseError, G as MantyxPluginToolRef, H as MantyxRunError, I as MantyxRunErrorInit, J as MantyxRunErrorModel, K as MantyxRunErrorTokens, N as MantyxScopeError, O as MantyxToolError, P as MantyxToolRef, Q as McpToolRef, S as ModelCatalog, U as ModelInfo, V as OAuthToken, W as OutputSchema, R as ReasoningLevel, X as RefreshOptions, Y as RefreshTokenSourceOptions, Z as ResultEvent, _ as RevokeOptions, $ as RunEvent, a0 as RunEventBase, a1 as RunModelInfo, a2 as RunResult, a3 as RunSpec, a4 as RunTokenUsage, a5 as ServerToolResultEvent, a6 as SessionInfo, a7 as SessionSpec, a8 as Supervisor, a9 as SupervisorAction, aa as SupervisorEvent, ab as ThinkingDeltaEvent, ac as TokenRequestReason, ad as TokenSource, ae as ToolBudget, af as ToolBudgetExceededEvent, ag as ToolBudgets, T as ToolRef, ah as ZodLikeObject, ai as defineLocalA2A, aj as defineLocalMcp, ak as defineLocalTool, al as isLocalA2ATool, am as isLocalMcpServer, an as isLocalTool, ao as mantyxA2A, ap as mantyxMcp, aq as mantyxPluginTool, ar as mantyxTool, as as parseRunOutput } from './client-LQlx7iYY.js';
 import { z } from 'zod';
 
 /**
@@ -52,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.11.0";
+declare const SDK_VERSION = "0.12.0";
 
 export { SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };

package/dist/index.js

@@ -23,7 +23,7 @@ import {
   readSseStream,
   toToolParametersWire,
   zodToJsonSchema
-} from "./chunk-DR625E6B.js";
+} from "./chunk-2K4BGJGJ.js";
 
 // src/oauth.ts
 var DEFAULT_OAUTH_BASE_URL = "https://app.mantyx.io";
@@ -245,7 +245,7 @@ function normalizeScope(scope) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.11.0";
+var SDK_VERSION = "0.12.0";
 export {
   AgentSession,
   DEFAULT_BASE_URL,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/oauth.ts","../src/version.ts"],"sourcesContent":["/**\n * MANTYX OAuth 2.0 refresh client: trade a stored refresh token for\n * short-lived access tokens, revoke tokens at sign-out, and expose\n * a {@link TokenSource} the {@link MantyxClient} HTTP layer calls\n * before every request (and again on 401).\n *\n * The library is intentionally **refresh-only**. It assumes the caller\n * already obtained the refresh token through their own sign-in flow\n * (Authorization Code + PKCE in a browser, native redirect, server-\n * side exchange — whatever fits the host application). The SDK does\n * not drive consent, does not initiate auth-code exchanges, and does\n * not bundle PKCE helpers.\n *\n * Wire contract (`docs/oauth.md`):\n *\n * - Token endpoint: `POST <baseUrl>/api/oauth/token`, form-encoded,\n *   `grant_type=refresh_token`. Echoes back the same `refresh_token`\n *   the client sent (refresh tokens are persistent and non-rotating).\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 long-lived; the caller persists\n *   them once at first sign-in (encrypted at rest) and the SDK re-mints\n *   access tokens from the same value on demand.\n */\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 uses to decide when to refresh.\n *\n * On the refresh grant the response's `refreshToken` is identical to\n * the value the client just sent (refresh tokens never rotate). The\n * field is surfaced for symmetry with whatever the calling app's\n * sign-in flow already does.\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 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 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 host application's\n   * sign-in flow). When omitted, the source mints one on the first\n   * call.\n   */\n  initialToken?: OAuthToken;\n}\n\n/**\n * Refresh-only wrapper around the MANTYX OAuth 2.0 authorization-server\n * endpoints. App-scoped (one per `{clientId, clientSecret}` pair);\n * construct independently of {@link MantyxClient}, then either call\n * {@link refresh} / {@link revoke} directly or hand a `TokenSource`\n * produced by {@link refreshTokenSource} to `MantyxClient` for fully\n * transparent refresh on every request.\n *\n * The client deliberately does **not** drive the authorization-code\n * exchange or any other \"initiate sign-in\" grant. The caller is\n * expected to obtain the refresh token through their own consent flow\n * and persist it before constructing this client.\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   * Mint a fresh access token from a stored refresh token. The\n   * returned `refreshToken` is identical to the input — refresh\n   * tokens are persistent and non-rotating, so the field is\n   * surfaced only for symmetry with the response shape.\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   * 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   * Pass `initialToken` if the calling app already has a non-expired\n   * access token in hand (e.g. straight out of the sign-in flow) to\n   * avoid an extra round-trip on the first request.\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  // -------------------------------------------------------------- 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// -------------------------------------------------------------- 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 (reason === \"unauthorized\" && t === cache.token) {\n        // If the inflight refresh was triggered by a benign cache miss\n        // and we observed an unauthorized hint after it started, fall\n        // through and mint again so the caller never gets a stale token.\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.11.0\";\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/oauth.ts","../src/version.ts"],"sourcesContent":["/**\n * MANTYX OAuth 2.0 refresh client: trade a stored refresh token for\n * short-lived access tokens, revoke tokens at sign-out, and expose\n * a {@link TokenSource} the {@link MantyxClient} HTTP layer calls\n * before every request (and again on 401).\n *\n * The library is intentionally **refresh-only**. It assumes the caller\n * already obtained the refresh token through their own sign-in flow\n * (Authorization Code + PKCE in a browser, native redirect, server-\n * side exchange — whatever fits the host application). The SDK does\n * not drive consent, does not initiate auth-code exchanges, and does\n * not bundle PKCE helpers.\n *\n * Wire contract (`docs/oauth.md`):\n *\n * - Token endpoint: `POST <baseUrl>/api/oauth/token`, form-encoded,\n *   `grant_type=refresh_token`. Echoes back the same `refresh_token`\n *   the client sent (refresh tokens are persistent and non-rotating).\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 long-lived; the caller persists\n *   them once at first sign-in (encrypted at rest) and the SDK re-mints\n *   access tokens from the same value on demand.\n */\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 uses to decide when to refresh.\n *\n * On the refresh grant the response's `refreshToken` is identical to\n * the value the client just sent (refresh tokens never rotate). The\n * field is surfaced for symmetry with whatever the calling app's\n * sign-in flow already does.\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 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 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 host application's\n   * sign-in flow). When omitted, the source mints one on the first\n   * call.\n   */\n  initialToken?: OAuthToken;\n}\n\n/**\n * Refresh-only wrapper around the MANTYX OAuth 2.0 authorization-server\n * endpoints. App-scoped (one per `{clientId, clientSecret}` pair);\n * construct independently of {@link MantyxClient}, then either call\n * {@link refresh} / {@link revoke} directly or hand a `TokenSource`\n * produced by {@link refreshTokenSource} to `MantyxClient` for fully\n * transparent refresh on every request.\n *\n * The client deliberately does **not** drive the authorization-code\n * exchange or any other \"initiate sign-in\" grant. The caller is\n * expected to obtain the refresh token through their own consent flow\n * and persist it before constructing this client.\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   * Mint a fresh access token from a stored refresh token. The\n   * returned `refreshToken` is identical to the input — refresh\n   * tokens are persistent and non-rotating, so the field is\n   * surfaced only for symmetry with the response shape.\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   * 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   * Pass `initialToken` if the calling app already has a non-expired\n   * access token in hand (e.g. straight out of the sign-in flow) to\n   * avoid an extra round-trip on the first request.\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  // -------------------------------------------------------------- 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// -------------------------------------------------------------- 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 (reason === \"unauthorized\" && t === cache.token) {\n        // If the inflight refresh was triggered by a benign cache miss\n        // and we observed an unauthorized hint after it started, fall\n        // through and mint again so the caller never gets a stale token.\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.12.0\";\n"],"mappings":"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","names":[]}

package/docs/agent-runs-protocol.md

@@ -361,8 +361,12 @@ The agent spec is the body shape used by `POST /agent-runs` and `POST
     "hive_consult_ontology": { "maxCalls": 4 },
     "scary_tool": { "maxCalls": 0 },
   },
+  "supervisor": {
+    // optional, see §4.8 — platform LLM judge; pass false to disable
+    "interval": 5,
+  },
   "metadata": {
-    // optional, see §4.8
+    // optional, see §4.9
     "customer": "acme",
     "env": "prod",
   },
@@ -844,7 +848,64 @@ during normal multi-entity reads. The loop-detection guard catches the
 pathological "same `(name, args)` batch over and over" case for that
 family without needing per-tool caps.
 
-### 4.8 `metadata` (developer-supplied KV for filtering)
+### 4.8 `supervisor` (run judge)
+
+`supervisor` controls the optional **run supervisor** — an LLM judge that
+periodically reviews the agent's transcript (reasoning, tool calls, tool
+results, visible text) and may steer the run:
+
+- **`on_track`** — no-op; the run continues.
+- **`redirect`** — a steering user message is injected; tools stay available.
+- **`finalize`** — the next turn is forced tools-disabled so the run lands a
+  clean final answer.
+
+Reviews fire every **`interval` LLM calls** (`completeTurn` invocations) at
+the bottom of tool-emitting rounds. Default interval is **5** when enabled.
+
+```jsonc
+"supervisor": {
+  "interval": 5     // optional — LLM calls between reviews; default 5
+}
+
+// or:
+"supervisor": false   // explicitly disable the platform judge for this run
+```
+
+| Field             | Type            | Required | Notes                                                                                                                        |
+| ----------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `interval`        | integer ≥ 1     | no       | Defaults to **5** when the supervisor is enabled and `interval` is omitted. Capped at **100** server-side.                   |
+| (literal `false`) | `false`         | no       | Disables the run supervisor for this run. `loopDetection` and `toolBudgets` still apply.                                       |
+
+**Defaults.** When `supervisor` is **omitted**, MANTYX enables the platform
+LLM judge on ephemeral runs. Pass `"supervisor": false` to opt out.
+
+**SDK-only usage.** When calling `@mantyx/ts-sdk` directly (not via
+`POST /agent-runs`), the supervisor is **off unless explicitly configured**:
+pass `supervisor: { review, interval? }` on `RunAgentOptions` to enable a
+caller-supplied judge, or pass `supervisor: false` (or omit the field) to
+keep it disabled. The wire field above controls the **platform-hosted** judge
+on API/ephemeral runs only.
+
+Validation (server-side, `400 invalid_request` on violation):
+
+| Constraint        | Limit |
+| ----------------- | ----- |
+| `interval` upper bound | `100` |
+
+**Inheritance for sessions.**
+
+- `POST /agent-sessions { supervisor }` — sets the session-default, applied
+  to every subsequent message run.
+- `POST /agent-sessions/:id/messages { supervisor }` — optional per-message
+  override; applies to that one run only and does not mutate the session's
+  stored value.
+
+**Observability.** Each review emits a SSE `supervisor` event (see §7) —
+including `on_track` checks — so SDK clients can render supervisor activity.
+When `action` is `redirect` or `finalize`, the pipeline has already applied
+the verdict by the time the event arrives.
+
+### 4.9 `metadata` (developer-supplied KV for filtering)
 
 `metadata` is a flat string→string KV that is **persisted alongside the run /
 session** and surfaced in the MANTYX dashboard. Use it to tag runs with your
@@ -962,9 +1023,6 @@ data: <utf-8 JSON>
 `<type>` and `<data>` shapes:
 
 ```jsonc
-// running message
-{ "seq": 1, "type": "started", "data": {} }
-
 // streamed assistant tokens (zero or more per turn)
 { "seq": 2, "type": "assistant_delta", "data": { "text": "Hello" } }
 
@@ -1001,6 +1059,11 @@ data: <utf-8 JSON>
 // is observability so SDK clients can render "memory budget exhausted" status notes.
 { "seq": 7, "type": "tool_budget_exceeded", "data": { "tool": "recall", "maxCalls": 4, "callIndex": 5 } }
 
+// run-supervisor check (see §4.8). Fired on every review — on_track included.
+{ "seq": 7, "type": "supervisor", "data": { "action": "on_track", "reason": "Agent is making progress.", "llmCalls": 5 } }
+{ "seq": 8, "type": "supervisor", "data": { "action": "redirect", "reason": "Stuck re-querying.", "redirect": "Answer from the data you already have.", "llmCalls": 10 } }
+{ "seq": 9, "type": "supervisor", "data": { "action": "finalize", "reason": "Enough to answer.", "llmCalls": 15 } }
+
 // terminal event
 // Every terminal `result` event also carries `tokens`, `turns`, and `model`
 // for cost attribution and dashboards — see §7.1. Older platforms (pre-
@@ -1241,18 +1304,18 @@ A reference SDK should:
    - Treat `thinking_delta` events as opt-in callback fodder; many UIs hide
      them by default. Their presence depends on `reasoningLevel > 0` and
      on the active model exposing thought parts.
-   - Accept `loopDetection` and `toolBudgets` from the caller and pass
-     them through unchanged (see §4.6 / §4.7). Both fields are _additive_:
-     omitting them keeps MANTYX's runtime defaults; passing
-     `loopDetection: false` opts out; passing `toolBudgets: {}` clears the
-     defaults; passing entries layers caller overrides on top of the
-     defaults.
-   - Treat `loop_detected` and `tool_budget_exceeded` SSE events as
-     observability-only — the server already substituted the synthetic
-     tool-results / steering nudges, so the SDK's job is just to surface
-     the event to the caller (status banner, log line, telemetry). Do
-     **not** abort the run on these events; the run continues through
-     `result` / `error` / `cancelled` as usual.
+   - Accept `loopDetection`, `toolBudgets`, and `supervisor` from the caller
+     and pass them through unchanged (see §4.6 / §4.7 / §4.8). All three are
+     _additive_: omitting them keeps MANTYX's runtime defaults; passing
+     `loopDetection: false` or `supervisor: false` opts out; passing
+     `toolBudgets: {}` clears the defaults; passing entries layers caller
+     overrides on top of the defaults.
+   - Treat `loop_detected`, `tool_budget_exceeded`, and `supervisor` SSE
+     events as observability-only — the server already substituted synthetic
+     tool-results / steering nudges / supervisor verdicts where applicable, so
+     the SDK's job is just to surface the event to the caller (status banner,
+     log line, telemetry). Do **not** abort the run on these events; the run
+     continues through `result` / `error` / `cancelled` as usual.
    - On terminal `result`, resolve the call. On `error` subtype, throw.
 4. Re-emit assistant deltas/events as a stream/iterator for callers who care
    about live output.
@@ -1269,4 +1332,4 @@ A reference SDK should:
 
 The npm package [`@mantyx/sdk`](https://www.npmjs.com/package/@mantyx/sdk) and the Go module
 [`github.com/mantyx/mantyx-go-sdk`](https://github.com/mantyx/mantyx-go-sdk) are reference implementations of this protocol
-(maintained in the official **mantyx-sdk** repositories).
+(maintained in the official **mantyx-sdk** repositories).

package/docs/wire-protocol.md

@@ -132,6 +132,10 @@ short-circuit, etc.) see `agent-runs-protocol.md` §4.
     "recall": { "maxCalls": 4 },
     "hive_consult_ontology": { "maxCalls": 4 },
   },
+  "supervisor": {
+    // optional; see §8.4 — platform LLM judge on ephemeral runs
+    "interval": 5,
+  },
   "metadata": { "customer": "acme" }, // optional, free-form k/v
 }
 ```
@@ -140,9 +144,9 @@ short-circuit, etc.) see `agent-runs-protocol.md` §4.
 
 Same body shape, posted to `POST /agent-sessions/:id/messages`. The session
 keeps the conversation history; per-message `tools`, `reasoningLevel`,
-`outputSchema`, `loopDetection`, and `toolBudgets` _replace_ the session's
-defaults for that single run only — the next run falls back to whatever
-the session was created with.
+`outputSchema`, `loopDetection`, `toolBudgets`, and `supervisor` _replace_
+the session's defaults for that single run only — the next run falls back to
+whatever the session was created with.
 
 ---
 
@@ -391,6 +395,7 @@ The vocabulary (`EphemeralEventType` in `bus.ts`):
 | `local_tool_result_in` | M → SDK   | Per client-resolved tool call                    | Informational mirror of the tool-result the SDK just posted, persisted for observability. Re-emitted to late subscribers so they can replay the conversation.                                                                               |
 | `loop_detected`        | M → SDK   | 0–2× per run (soft nudge + optional hard cutoff) | Observability for the loop-detection guard (see §8). The server already substituted the synthetic skip + steering nudge — SDK clients render a status note (`looping — nudged` / `looping — gave up`) and otherwise leave the run alone.    |
 | `tool_budget_exceeded` | M → SDK   | Per intercepted tool call                        | Observability for per-tool call budgets (see §8). The synthetic `tool_result` carrying the "budget exceeded — pivot or finalize" body lands on the normal tool-result channel; this event is purely so SDK clients can surface a UI banner. |
+| `supervisor`           | M → SDK   | 0–N× per run (every `interval` LLM calls)        | Run-supervisor check (see §4.7 / §8.4). Fired on **every** review — including `on_track` — so SDK clients can render supervisor activity. When the judge steers the run (`redirect` / `finalize`), the pipeline has already injected the steering message or forced a tools-disabled finalize turn. |
 | `assistant_message`    | M → SDK   | 1× per turn                                      | Final assistant message for the turn (concatenated, persistence-ready).                                                                                                                                                                     |
 | `result`               | M → SDK   | 1× terminal                                      | Successful completion. Carries the final assistant text and run summary.                                                                                                                                                                    |
 | `error`                | M → SDK   | 1× terminal                                      | Failure. Carries `error` (message), `code` / `errorClass` (category), `finishReason`, and an optional `partialText` salvage payload. See §4.7.                                                                                              |
@@ -640,7 +645,45 @@ re-parsing tool-result bodies.
 
 See §8 for the wire-spec field that defines budgets.
 
-### 4.7 Terminal events
+### 4.7 `supervisor`
+
+```jsonc
+// on_track — the judge reviewed the run and decided not to intervene
+{ "seq": 15, "type": "supervisor",
+  "data": { "action": "on_track", "reason": "Agent is gathering context via search before answering.", "llmCalls": 5 } }
+
+// redirect — a steering user message was injected; the agent keeps its tools
+{ "seq": 20, "type": "supervisor",
+  "data": { "action": "redirect", "reason": "Repeating the same search with identical args.", "redirect": "Stop re-querying; synthesize an answer from the results you already have.", "llmCalls": 10 } }
+
+// finalize — the run was forced to wrap up on a tools-disabled turn
+{ "seq": 25, "type": "supervisor",
+  "data": { "action": "finalize", "reason": "Enough evidence to answer; further tool use is unlikely to help.", "llmCalls": 15 } }
+```
+
+| Field      | Type    | Notes                                                                                                                                                                                                                         |
+| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`   | string  | One of `"on_track"`, `"redirect"`, `"finalize"`.                                                                                                                                                                              |
+| `reason`   | string  | One- or two-sentence explanation from the judge.                                                                                                                                                                              |
+| `redirect` | string  | Present when `action === "redirect"`: the steering message injected into the conversation (same text the agent sees as a user message). Omitted for `on_track` / `finalize`.                                                 |
+| `llmCalls` | integer | Number of LLM calls (`completeTurn` invocations) completed when this review fired. Matches the pipeline's `modelInvocations` counter at the check boundary.                                                                   |
+
+Observability for the run-supervisor guard (see §8.4). The event fires on
+**every** check, not only when the judge intervenes — `on_track` reviews are
+included so SDK clients can show "supervisor reviewed" activity without
+inferring it from missing events.
+
+When `action` is `redirect` or `finalize`, the pipeline has already applied
+the verdict by the time this event arrives: a steering user message was
+appended (`redirect`) or the next turn was forced tools-disabled
+(`finalize`). SDK clients should render a status note and **not** try to
+steer the run themselves.
+
+Pass `"supervisor": false` in the spec (§8.4) to disable the platform judge
+for a run. Omission keeps the runtime default (supervisor **enabled** on
+ephemeral runs).
+
+### 4.8 Terminal events
 
 ```jsonc
 // Every terminal `result` and `error` event also carries `tokens`, `turns`,
@@ -692,7 +735,7 @@ SDK can re-fetch via `GET /agent-runs/:runId` will have:
 | `error`         | Same string as `data.error`.                                                                                             |
 | `failureReason` | `{ "errorClass": "truncation", "finishReason": "max_tokens" }` (JSON object, future-proof for additional triage fields). |
 
-### 4.7.1 Cost-attribution fields (`tokens`, `turns`, `model`)
+### 4.8.1 Cost-attribution fields (`tokens`, `turns`, `model`)
 
 Every terminal `result` and `error` event carries three additional
 fields so callers can drive cost dashboards, per-turn budgets, and
@@ -1030,20 +1073,67 @@ banners without re-parsing tool-result bodies:
 - `loop_detected` — fired on the soft nudge and again on the hard cutoff
   if reached. See §4.5.
 - `tool_budget_exceeded` — fired each time a call is intercepted. See §4.6.
+- `supervisor` — fired on every run-supervisor review (`on_track`,
+  `redirect`, or `finalize`). See §4.7.
+
+Both guard events (`loop_detected`, `tool_budget_exceeded`) are
+observability-only: the server has already substituted the synthetic
+tool-result / steering nudge by the time the SDK sees the event. The
+`supervisor` event is also observability-only when `action` is
+`redirect` / `finalize` — the pipeline already applied the verdict. The
+run continues to its terminal `result` / `error` / `cancelled` as usual.
+
+### 8.4 `supervisor` (run judge)
+
+An optional LLM **run supervisor** periodically reviews the agent's
+transcript (reasoning, tool calls, tool results, visible text) and may
+steer the run:
+
+| Verdict     | Server action                                                                                                                                      |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `on_track`  | No-op — the run continues unchanged.                                                                                                               |
+| `redirect`  | A steering **user message** is injected; tools stay available on the next turn.                                                                    |
+| `finalize`  | The next turn is forced **tools-disabled** so the run lands a clean final answer (optionally prefaced by the supervisor's message).                |
+
+Reviews fire every **`interval` LLM calls** (`completeTurn` invocations),
+measured at the bottom of tool-emitting rounds. Default interval is **5**
+when the field is omitted.
+
+```jsonc
+"supervisor": {
+  "interval": 5     // optional — LLM calls between reviews; default 5
+}
+
+// or:
+"supervisor": false   // explicitly disable the platform judge for this run
+```
+
+| Field      | Type            | Notes                                                                                                                              |
+| ---------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `interval` | integer ≥ 1     | Optional. Default **5** when omitted. Capped at **100** server-side.                                                                |
+| (literal `false`) | `false`  | Disables the run supervisor for this run. Loop detection and tool budgets still apply.                                             |
+
+**Defaults.** When `supervisor` is **omitted**, MANTYX enables the platform
+LLM judge on ephemeral runs (web chat enables it separately via the chat
+runner). Pass `"supervisor": false` to opt out.
+
+**SDK-only runs.** When a caller uses `@mantyx/ts-sdk` directly (not via
+`POST /agent-runs`), the supervisor is **off unless explicitly configured**:
+pass a `RunAgentSupervisor` object with a `review` callback to enable it, or
+pass `supervisor: false` (or omit the field) to keep it disabled. The wire
+field above controls the **platform-hosted** judge on ephemeral API runs only.
 
-Both events are observability-only: the server has already substituted
-the synthetic tool-result / steering nudge by the time the SDK sees the
-event. The run continues to its terminal `result` / `error` / `cancelled`
-as usual.
+Each review emits a SSE `supervisor` event (§4.7). Supervisor LLM usage is
+recorded under the `supervisor` usage surface for cost attribution.
 
-### 8.4 Session inheritance
+### 8.5 Session inheritance
 
-Like `reasoningLevel` and `outputSchema`, both fields support
+Like `reasoningLevel` and `outputSchema`, the run-guard fields support
 session-default + per-message override:
 
-- `POST /agent-sessions { loopDetection, toolBudgets }` — sets the
+- `POST /agent-sessions { loopDetection, toolBudgets, supervisor }` — sets the
   session-default applied to every subsequent message run.
-- `POST /agent-sessions/:id/messages { loopDetection, toolBudgets }` —
+- `POST /agent-sessions/:id/messages { loopDetection, toolBudgets, supervisor }` —
   optional per-message override. Applies to that one run only and does
   not mutate the session's stored value.
 
@@ -1215,17 +1305,17 @@ A reference SDK should:
       source-of-truth schema (Zod / Pydantic / etc.) — the server enforces
       JSON shape via the provider, but transient model errors can still
       produce strings that fail to parse in rare cases.
-- [ ] Accept `loopDetection` and `toolBudgets` from the caller and pass
-      them through unchanged (see §8). Both are _additive_ — omitting
-      them keeps the runtime defaults; passing `loopDetection: false` opts
-      out; passing `toolBudgets: {}` clears the defaults; passing entries
-      layers caller overrides on top of the defaults. Do **not** translate
-      to vendor-specific knobs.
-- [ ] Treat `loop_detected` and `tool_budget_exceeded` SSE events as
-      observability-only (see §4.5 / §4.6). Surface them as status notes
-      / log lines / telemetry — the server already substituted the
-      synthetic tool-results / steering nudges, so the SDK should keep
-      consuming the stream until the terminal event lands.
+- [ ] Accept `loopDetection`, `toolBudgets`, and `supervisor` from the caller
+      and pass them through unchanged (see §8). All three are _additive_ —
+      omitting them keeps the runtime defaults; passing `loopDetection: false`
+      or `supervisor: false` opts out; passing `toolBudgets: {}` clears the
+      defaults; passing entries layers caller overrides on top of the defaults.
+      Do **not** translate to vendor-specific knobs.
+- [ ] Treat `loop_detected`, `tool_budget_exceeded`, and `supervisor` SSE
+      events as observability-only (see §4.5 / §4.6 / §4.7). Surface them as
+      status notes / log lines / telemetry — the server already substituted
+      synthetic tool-results / steering nudges / supervisor verdicts, so the
+      SDK should keep consuming the stream until the terminal event lands.
 - [ ] Maintain three local-callback registries (or one tagged-union
       registry), keyed by `name`: - generic local tools (`kind: "local"`), - local A2A peers (`kind: "a2a_local"`, indexed by some Agent Card
       field — typically `agentCard.url`), - local MCP servers (`kind: "mcp_local"`, indexed by the SDK-side
@@ -1262,4 +1352,4 @@ A reference SDK should:
 - [A2A spec](https://google.github.io/A2A/specification/) — canonical
   Agent Card schema.
 - [MCP spec](https://spec.modelcontextprotocol.io/) — canonical `Tool` and
-  `Implementation` shapes.
+  `Implementation` shapes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantyx/sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MANTYX as a hosted agent runtime: define ephemeral agents, mix server-side MANTYX tools with locally-executed tools, run them remotely.",
   "type": "module",
   "main": "./dist/index.cjs",