@mantyx/sdk 0.11.0 → 0.12.0

package/dist/{client-Byb0Zdo7.d.ts → client-LQlx7iYY.d.ts}

@@ -843,6 +843,22 @@ interface AgentSpecBase {
      * `docs/agent-runs-protocol.md` §4.7.
      */
     toolBudgets?: ToolBudgets;
+    /**
+     * Run-supervisor (platform LLM judge). Periodically reviews the agent's
+     * transcript and may steer the run (`on_track`, `redirect`, `finalize`).
+     *
+     * Pass an object to override the review interval, or `false` to explicitly
+     * disable the platform judge for this run / session. When omitted on
+     * ephemeral API runs, MANTYX enables the supervisor (default interval `5`).
+     * SDK-only runs (`runAgent` without the HTTP API) keep the supervisor off
+     * unless you pass a value here. See `docs/agent-runs-protocol.md` §4.8.
+     *
+     * Each review emits an observability-only `supervisor` SSE event — including
+     * `on_track` checks — so the SDK can render supervisor activity. When
+     * `action` is `redirect` or `finalize`, the pipeline has already applied
+     * the verdict by the time the event arrives.
+     */
+    supervisor?: Supervisor | false;
     /**
      * Flat string→string KV carried alongside the run / session for
      * observability. Use it to tag runs with your own application identifiers
@@ -925,6 +941,20 @@ interface ToolBudget {
  * entirely to keep the defaults.
  */
 type ToolBudgets = Record<string, ToolBudget>;
+/**
+ * Run-supervisor configuration. See {@link AgentSpecBase.supervisor} for the
+ * full semantics. Pass `false` (instead of an object) to disable the platform
+ * judge for the run / session.
+ *
+ * `interval` is optional; when omitted the MANTYX runtime default is **5**
+ * LLM calls between reviews. Server-side upper bound: `100`.
+ */
+interface Supervisor {
+    /** LLM calls (`completeTurn` invocations) between supervisor reviews. */
+    interval?: number;
+}
+/** Verdict from a run-supervisor review. */
+type SupervisorAction = "on_track" | "redirect" | "finalize";
 /**
  * Per-run token totals attached to terminal `result` / `error` events
  * (and to the `GET /agent-runs/:runId` snapshot) by MANTYX ≥ 2026-09.
@@ -1164,6 +1194,30 @@ interface ToolBudgetExceededEvent extends RunEventBase {
      */
     callIndex: number;
 }
+/**
+ * Observability event fired on every run-supervisor review — including
+ * `on_track` checks. When `action` is `redirect` or `finalize`, the pipeline
+ * has already injected the steering message or forced a tools-disabled turn
+ * by the time this event arrives; the SDK should render a status note and
+ * keep consuming the stream.
+ */
+interface SupervisorEvent extends RunEventBase {
+    type: "supervisor";
+    /** One of `"on_track"`, `"redirect"`, `"finalize"`. */
+    action: SupervisorAction;
+    /** One- or two-sentence explanation from the judge. */
+    reason: string;
+    /**
+     * Present when `action === "redirect"`: the steering user message injected
+     * into the conversation. Omitted for `on_track` / `finalize`.
+     */
+    redirect?: string;
+    /**
+     * Number of LLM calls completed when this review fired. Matches the
+     * pipeline's `modelInvocations` counter at the check boundary.
+     */
+    llmCalls: number;
+}
 interface ResultEvent extends RunEventBase {
     type: "result";
     subtype: string;
@@ -1233,7 +1287,7 @@ interface CancelledEvent extends RunEventBase {
     type: "cancelled";
     reason?: string;
 }
-type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | LoopDetectedEvent | ToolBudgetExceededEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
+type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | LoopDetectedEvent | ToolBudgetExceededEvent | SupervisorEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
     type: string;
     [key: string]: unknown;
 });
@@ -1376,6 +1430,12 @@ declare class AgentSession {
          * and does not mutate the session's stored value.
          */
         toolBudgets?: ToolBudgets;
+        /**
+         * Per-message override for `supervisor`. Applies only to this run
+         * and does not mutate the session's stored value. Pass `false` to
+         * disable the platform judge for this single turn.
+         */
+        supervisor?: Supervisor | false;
     }): Promise<RunResult>;
     stream(prompt: string, opts?: {
         signal?: AbortSignal;
@@ -1384,6 +1444,7 @@ declare class AgentSession {
         outputSchema?: OutputSchema;
         loopDetection?: LoopDetection | false;
         toolBudgets?: ToolBudgets;
+        supervisor?: Supervisor | false;
     }): AsyncGenerator<RunEvent, void, void>;
     private buildSessionMessageBody;
     history(): Promise<Array<{
@@ -1434,4 +1495,4 @@ interface LocalHandlers {
  */
 declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
 
-export { type RunEvent as $, type A2AToolRef as A, MantyxOAuthError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxParseError as F, type MantyxPluginToolRef as G, MantyxRunError as H, type MantyxRunErrorInit as I, type MantyxRunErrorModel as J, type MantyxRunErrorTokens as K, type LocalA2ATool as L, MantyxClient as M, MantyxScopeError as N, MantyxToolError as O, type MantyxToolRef as P, type McpToolRef as Q, type ReasoningLevel as R, type ModelCatalog as S, type ToolRef as T, type ModelInfo as U, type OAuthToken as V, type OutputSchema as W, type RefreshOptions as X, type RefreshTokenSourceOptions as Y, type ResultEvent as Z, type RevokeOptions as _, AgentSession as a, type RunEventBase as a0, type RunModelInfo as a1, type RunResult as a2, type RunSpec as a3, type RunTokenUsage as a4, type ServerToolResultEvent as a5, type SessionInfo as a6, type SessionSpec as a7, type ThinkingDeltaEvent as a8, type TokenRequestReason as a9, type TokenSource as aa, type ToolBudget as ab, type ToolBudgetExceededEvent as ac, type ToolBudgets as ad, type ZodLikeObject as ae, defineLocalA2A as af, defineLocalMcp as ag, defineLocalTool as ah, isLocalA2ATool as ai, isLocalMcpServer as aj, isLocalTool as ak, mantyxA2A as al, mantyxMcp as am, mantyxPluginTool as an, mantyxTool as ao, parseRunOutput as ap, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, DEFAULT_OAUTH_BASE_URL as e, DEFAULT_REFRESH_SKEW_MS as f, type DefineLocalA2AOptions as g, type DefineLocalMcpOptions as h, type DefineLocalToolOptions as i, type LocalHandlers as j, type LocalMcpHttpTransport as k, type LocalMcpServer as l, type LocalMcpStdioTransport as m, type LocalTool as n, type LocalToolCallEvent as o, type LocalToolResultInEvent as p, type LoopDetectedEvent as q, type LoopDetection as r, type MantyxA2AOptions as s, MantyxAuthError as t, type MantyxClientOptions as u, MantyxError as v, type MantyxMcpOptions as w, MantyxNetworkError as x, MantyxOAuthClient as y, type MantyxOAuthClientOptions as z };
+export { type RunEvent as $, type A2AToolRef as A, MantyxOAuthError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxParseError as F, type MantyxPluginToolRef as G, MantyxRunError as H, type MantyxRunErrorInit as I, type MantyxRunErrorModel as J, type MantyxRunErrorTokens as K, type LocalA2ATool as L, MantyxClient as M, MantyxScopeError as N, MantyxToolError as O, type MantyxToolRef as P, type McpToolRef as Q, type ReasoningLevel as R, type ModelCatalog as S, type ToolRef as T, type ModelInfo as U, type OAuthToken as V, type OutputSchema as W, type RefreshOptions as X, type RefreshTokenSourceOptions as Y, type ResultEvent as Z, type RevokeOptions as _, AgentSession as a, type RunEventBase as a0, type RunModelInfo as a1, type RunResult as a2, type RunSpec as a3, type RunTokenUsage as a4, type ServerToolResultEvent as a5, type SessionInfo as a6, type SessionSpec as a7, type Supervisor as a8, type SupervisorAction as a9, type SupervisorEvent as aa, type ThinkingDeltaEvent as ab, type TokenRequestReason as ac, type TokenSource as ad, type ToolBudget as ae, type ToolBudgetExceededEvent as af, type ToolBudgets as ag, type ZodLikeObject as ah, defineLocalA2A as ai, defineLocalMcp as aj, defineLocalTool as ak, isLocalA2ATool as al, isLocalMcpServer as am, isLocalTool as an, mantyxA2A as ao, mantyxMcp as ap, mantyxPluginTool as aq, mantyxTool as ar, parseRunOutput as as, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, DEFAULT_OAUTH_BASE_URL as e, DEFAULT_REFRESH_SKEW_MS as f, type DefineLocalA2AOptions as g, type DefineLocalMcpOptions as h, type DefineLocalToolOptions as i, type LocalHandlers as j, type LocalMcpHttpTransport as k, type LocalMcpServer as l, type LocalMcpStdioTransport as m, type LocalTool as n, type LocalToolCallEvent as o, type LocalToolResultInEvent as p, type LoopDetectedEvent as q, type LoopDetection as r, type MantyxA2AOptions as s, MantyxAuthError as t, type MantyxClientOptions as u, MantyxError as v, type MantyxMcpOptions as w, MantyxNetworkError as x, MantyxOAuthClient as y, type MantyxOAuthClientOptions as z };

package/dist/index.cjs

@@ -1102,6 +1102,9 @@ var AgentSession = class {
     if (opts.toolBudgets !== void 0) {
       body.toolBudgets = normalizeToolBudgets(opts.toolBudgets);
     }
+    if (opts.supervisor !== void 0) {
+      body.supervisor = normalizeSupervisor(opts.supervisor);
+    }
     return body;
   }
   async history() {
@@ -1142,6 +1145,9 @@ function serializeAgentSpec(spec, extra = {}) {
   if (spec.toolBudgets !== void 0) {
     body.toolBudgets = normalizeToolBudgets(spec.toolBudgets);
   }
+  if (spec.supervisor !== void 0) {
+    body.supervisor = normalizeSupervisor(spec.supervisor);
+  }
   if (spec.budgets) body.budgets = spec.budgets;
   if (spec.metadata && Object.keys(spec.metadata).length > 0) body.metadata = spec.metadata;
   if (extra.prompt !== void 0) body.prompt = extra.prompt;
@@ -1346,6 +1352,19 @@ function assertThreshold(label, value, min) {
 var TOOL_BUDGETS_MAX_ENTRIES = 32;
 var TOOL_BUDGET_MAX_NAME_LEN = 120;
 var TOOL_BUDGET_MAX_CALLS = 1e3;
+function normalizeSupervisor(value) {
+  if (value === false) return false;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MantyxError(
+      `supervisor must be an object or the literal \`false\`, got ${JSON.stringify(value)}`
+    );
+  }
+  const out = {};
+  if (value.interval !== void 0) {
+    out.interval = assertThreshold("supervisor.interval", value.interval, 1);
+  }
+  return out;
+}
 function normalizeToolBudgets(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new MantyxError(
@@ -1700,7 +1719,7 @@ function normalizeScope(scope) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.11.0";
+var SDK_VERSION = "0.12.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentSession,