@mantyx/sdk 0.10.1 → 0.12.0

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

@@ -47,6 +47,30 @@ declare class MantyxToolError extends MantyxError {
     readonly toolName: string;
     constructor(toolName: string, message: string);
 }
+/**
+ * Per-run token totals attached to terminal `result` / `error`
+ * events. See `docs/agent-runs-protocol.md` §7.1 for the per-provider
+ * mapping and the relationship between buckets. Re-exported from
+ * `client.ts` so error consumers can pattern-match the triple without
+ * a second import.
+ */
+interface MantyxRunErrorTokens {
+    inputTokens: number;
+    cachedTokens: number;
+    reasoningTokens: number;
+    outputTokens: number;
+}
+/**
+ * Resolved model that executed the run. Surfaced on terminal events
+ * by MANTYX ≥ 2026-09. See `docs/agent-runs-protocol.md` §7.1. The
+ * `provider` empty / undefined is the "no usage data" sentinel.
+ */
+interface MantyxRunErrorModel {
+    id: string;
+    provider: string;
+    vendorModelId: string;
+    reasoningEffort?: string;
+}
 /**
  * Optional triage attributes the runner attaches to terminal `error`
  * events. Mirrors the wire fields described in
@@ -83,6 +107,17 @@ interface MantyxRunErrorInit {
      * Informational; the SDK still owns the actual retry decision.
      */
     retryable?: boolean;
+    /**
+     * Per-run token totals from the terminal event. Present against
+     * MANTYX ≥ 2026-09 — see {@link MantyxRunErrorTokens} and
+     * `docs/agent-runs-protocol.md` §7.1. Includes the failing model
+     * call's usage when the run errored mid-loop.
+     */
+    tokens?: MantyxRunErrorTokens;
+    /** Total model invocations for the run, including the failing call. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link MantyxRunErrorModel}. */
+    model?: MantyxRunErrorModel;
 }
 declare class MantyxRunError extends MantyxError {
     readonly runId: string;
@@ -95,6 +130,12 @@ declare class MantyxRunError extends MantyxError {
     readonly partialText: string | undefined;
     /** See {@link MantyxRunErrorInit.retryable}. */
     readonly retryable: boolean | undefined;
+    /** See {@link MantyxRunErrorInit.tokens}. */
+    readonly tokens: MantyxRunErrorTokens | undefined;
+    /** See {@link MantyxRunErrorInit.turns}. */
+    readonly turns: number | undefined;
+    /** See {@link MantyxRunErrorInit.model}. */
+    readonly model: MantyxRunErrorModel | undefined;
     constructor(runId: string, subtype: string, message: string, init?: MantyxRunErrorInit);
 }
 /**
@@ -802,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
@@ -884,10 +941,116 @@ 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.
+ *
+ * Aggregated across every model invocation for the run. See
+ * `docs/agent-runs-protocol.md` §7.1 for the per-provider mapping and
+ * the relationship between buckets (`inputTokens` / `outputTokens` are
+ * the billable totals; `cachedTokens` and `reasoningTokens` are
+ * diagnostic breakdowns _inside_ those two totals, not separate
+ * additive buckets).
+ *
+ * Older servers omit the cost-attribution triple entirely; SDK callers
+ * detect "no usage data" by checking `result.model?.provider` is empty
+ * / undefined.
+ */
+interface RunTokenUsage {
+    /**
+     * Total billable input tokens — fresh prompt tokens plus the
+     * cached-read slice the provider still bills (at a discount) plus
+     * any cache-creation tokens plus tool-prompt tokens. Equal to the
+     * sum of every provider-reported input bucket for the run.
+     */
+    inputTokens: number;
+    /**
+     * The discounted slice of `inputTokens` that came from a prompt
+     * cache hit (Anthropic prompt caching, OpenAI cached prompt, Gemini
+     * implicit cache). `0` when the provider doesn't report cache reads
+     * or the run didn't hit cache.
+     */
+    cachedTokens: number;
+    /**
+     * Non-visible thinking tokens. **Already counted inside
+     * `outputTokens`** — surfaced separately so dashboards can break out
+     * "thinking cost" vs visible output. `0` when the model didn't
+     * reason or didn't report it.
+     */
+    reasoningTokens: number;
+    /**
+     * All tokens the model emitted for this run, visible + reasoning.
+     * Matches the provider's "completion tokens" / "output tokens"
+     * billing line.
+     */
+    outputTokens: number;
+}
+/**
+ * The resolved model the platform stamped onto the run, surfaced on
+ * terminal `result` / `error` events (and `GET /agent-runs/:runId`)
+ * by MANTYX ≥ 2026-09. See `docs/agent-runs-protocol.md` §7.1.
+ */
+interface RunModelInfo {
+    /**
+     * Catalog id — the same string a caller would pass back as
+     * `modelId` to re-select this exact entry (e.g. `"platform:demo"`,
+     * `"provider:cmf…"`). Empty string against legacy fallbacks that
+     * didn't synthesise a catalog id.
+     */
+    id: string;
+    /**
+     * Lowercase provider id: `"openai"`, `"anthropic"`, `"google"`,
+     * `"azure-openai"`. Empty string against legacy runners that don't
+     * report usage data — SDK callers use that as the "no usage data"
+     * signal.
+     */
+    provider: string;
+    /**
+     * The model id the platform actually sent to the provider (e.g.
+     * `"gpt-5.4-mini"`, `"claude-opus-4-7"`, `"gemini-2.5-pro"`).
+     */
+    vendorModelId: string;
+    /**
+     * `"off" | "low" | "medium" | "high"`. Omitted when the provider
+     * doesn't expose a reasoning-level knob or the run didn't request
+     * one.
+     */
+    reasoningEffort?: string;
+}
 interface RunResult {
     runId: string;
     text: string;
     events: RunEvent[];
+    /**
+     * Per-run token totals from the terminal event. Undefined against
+     * MANTYX servers older than 2026-09 (the "no usage data" signal is
+     * `result.model?.provider` being empty / undefined). See
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     */
+    tokens?: RunTokenUsage;
+    /**
+     * Total `engine.completeTurn(...)` invocations for the run,
+     * including the failing call when a run errored mid-loop. A
+     * single-shot run reports `1`; a tool loop is `>= 2`. Undefined
+     * against legacy MANTYX servers.
+     */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface RunEventBase {
     seq: number;
@@ -1031,11 +1194,44 @@ 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;
     text?: string;
     error?: string;
+    /**
+     * Per-run token totals. Present against MANTYX ≥ 2026-09 — see
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     */
+    tokens?: RunTokenUsage;
+    /** Total model invocations for the run. See {@link RunResult.turns}. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface ErrorEvent extends RunEventBase {
     type: "error";
@@ -1074,12 +1270,24 @@ interface ErrorEvent extends RunEventBase {
      * Informational; the SDK still owns the actual retry decision.
      */
     retryable?: boolean;
+    /**
+     * Per-run token totals. Present against MANTYX ≥ 2026-09 — see
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     * The pipeline counts the failing model call too, so a run that
+     * threw on the first turn reports `turns: 1` with that call's
+     * tokens already aggregated.
+     */
+    tokens?: RunTokenUsage;
+    /** Total model invocations for the run, including the failing call. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface CancelledEvent extends RunEventBase {
     type: "cancelled";
     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;
 });
@@ -1222,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;
@@ -1230,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<{
@@ -1280,4 +1495,4 @@ interface LocalHandlers {
  */
 declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
 
-export { type RunResult as $, type A2AToolRef as A, MantyxOAuthError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxParseError as F, type MantyxPluginToolRef as G, MantyxRunError as H, type MantyxRunErrorInit as I, MantyxScopeError as J, MantyxToolError as K, type LocalA2ATool as L, MantyxClient as M, type MantyxToolRef as N, type McpToolRef as O, type ModelCatalog as P, type ModelInfo as Q, type ReasoningLevel as R, type OAuthToken as S, type ToolRef as T, type OutputSchema as U, type RefreshOptions as V, type RefreshTokenSourceOptions as W, type ResultEvent as X, type RevokeOptions as Y, type RunEvent as Z, type RunEventBase as _, AgentSession as a, type RunSpec as a0, type ServerToolResultEvent as a1, type SessionInfo as a2, type SessionSpec as a3, type ThinkingDeltaEvent as a4, type TokenRequestReason as a5, type TokenSource as a6, type ToolBudget as a7, type ToolBudgetExceededEvent as a8, type ToolBudgets as a9, type ZodLikeObject as aa, defineLocalA2A as ab, defineLocalMcp as ac, defineLocalTool as ad, isLocalA2ATool as ae, isLocalMcpServer as af, isLocalTool as ag, mantyxA2A as ah, mantyxMcp as ai, mantyxPluginTool as aj, mantyxTool as ak, parseRunOutput as al, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, DEFAULT_OAUTH_BASE_URL as e, DEFAULT_REFRESH_SKEW_MS as f, type DefineLocalA2AOptions as g, type DefineLocalMcpOptions as h, type DefineLocalToolOptions as i, type LocalHandlers as j, type LocalMcpHttpTransport as k, type LocalMcpServer as l, type LocalMcpStdioTransport as m, type LocalTool as n, type LocalToolCallEvent as o, type LocalToolResultInEvent as p, type LoopDetectedEvent as q, type LoopDetection as r, type MantyxA2AOptions as s, MantyxAuthError as t, type MantyxClientOptions as u, MantyxError as v, type MantyxMcpOptions as w, MantyxNetworkError as x, MantyxOAuthClient as y, type MantyxOAuthClientOptions as z };
+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/{client-CZUVldDx.d.ts → client-LQlx7iYY.d.ts}

@@ -47,6 +47,30 @@ declare class MantyxToolError extends MantyxError {
     readonly toolName: string;
     constructor(toolName: string, message: string);
 }
+/**
+ * Per-run token totals attached to terminal `result` / `error`
+ * events. See `docs/agent-runs-protocol.md` §7.1 for the per-provider
+ * mapping and the relationship between buckets. Re-exported from
+ * `client.ts` so error consumers can pattern-match the triple without
+ * a second import.
+ */
+interface MantyxRunErrorTokens {
+    inputTokens: number;
+    cachedTokens: number;
+    reasoningTokens: number;
+    outputTokens: number;
+}
+/**
+ * Resolved model that executed the run. Surfaced on terminal events
+ * by MANTYX ≥ 2026-09. See `docs/agent-runs-protocol.md` §7.1. The
+ * `provider` empty / undefined is the "no usage data" sentinel.
+ */
+interface MantyxRunErrorModel {
+    id: string;
+    provider: string;
+    vendorModelId: string;
+    reasoningEffort?: string;
+}
 /**
  * Optional triage attributes the runner attaches to terminal `error`
  * events. Mirrors the wire fields described in
@@ -83,6 +107,17 @@ interface MantyxRunErrorInit {
      * Informational; the SDK still owns the actual retry decision.
      */
     retryable?: boolean;
+    /**
+     * Per-run token totals from the terminal event. Present against
+     * MANTYX ≥ 2026-09 — see {@link MantyxRunErrorTokens} and
+     * `docs/agent-runs-protocol.md` §7.1. Includes the failing model
+     * call's usage when the run errored mid-loop.
+     */
+    tokens?: MantyxRunErrorTokens;
+    /** Total model invocations for the run, including the failing call. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link MantyxRunErrorModel}. */
+    model?: MantyxRunErrorModel;
 }
 declare class MantyxRunError extends MantyxError {
     readonly runId: string;
@@ -95,6 +130,12 @@ declare class MantyxRunError extends MantyxError {
     readonly partialText: string | undefined;
     /** See {@link MantyxRunErrorInit.retryable}. */
     readonly retryable: boolean | undefined;
+    /** See {@link MantyxRunErrorInit.tokens}. */
+    readonly tokens: MantyxRunErrorTokens | undefined;
+    /** See {@link MantyxRunErrorInit.turns}. */
+    readonly turns: number | undefined;
+    /** See {@link MantyxRunErrorInit.model}. */
+    readonly model: MantyxRunErrorModel | undefined;
     constructor(runId: string, subtype: string, message: string, init?: MantyxRunErrorInit);
 }
 /**
@@ -802,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
@@ -884,10 +941,116 @@ 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.
+ *
+ * Aggregated across every model invocation for the run. See
+ * `docs/agent-runs-protocol.md` §7.1 for the per-provider mapping and
+ * the relationship between buckets (`inputTokens` / `outputTokens` are
+ * the billable totals; `cachedTokens` and `reasoningTokens` are
+ * diagnostic breakdowns _inside_ those two totals, not separate
+ * additive buckets).
+ *
+ * Older servers omit the cost-attribution triple entirely; SDK callers
+ * detect "no usage data" by checking `result.model?.provider` is empty
+ * / undefined.
+ */
+interface RunTokenUsage {
+    /**
+     * Total billable input tokens — fresh prompt tokens plus the
+     * cached-read slice the provider still bills (at a discount) plus
+     * any cache-creation tokens plus tool-prompt tokens. Equal to the
+     * sum of every provider-reported input bucket for the run.
+     */
+    inputTokens: number;
+    /**
+     * The discounted slice of `inputTokens` that came from a prompt
+     * cache hit (Anthropic prompt caching, OpenAI cached prompt, Gemini
+     * implicit cache). `0` when the provider doesn't report cache reads
+     * or the run didn't hit cache.
+     */
+    cachedTokens: number;
+    /**
+     * Non-visible thinking tokens. **Already counted inside
+     * `outputTokens`** — surfaced separately so dashboards can break out
+     * "thinking cost" vs visible output. `0` when the model didn't
+     * reason or didn't report it.
+     */
+    reasoningTokens: number;
+    /**
+     * All tokens the model emitted for this run, visible + reasoning.
+     * Matches the provider's "completion tokens" / "output tokens"
+     * billing line.
+     */
+    outputTokens: number;
+}
+/**
+ * The resolved model the platform stamped onto the run, surfaced on
+ * terminal `result` / `error` events (and `GET /agent-runs/:runId`)
+ * by MANTYX ≥ 2026-09. See `docs/agent-runs-protocol.md` §7.1.
+ */
+interface RunModelInfo {
+    /**
+     * Catalog id — the same string a caller would pass back as
+     * `modelId` to re-select this exact entry (e.g. `"platform:demo"`,
+     * `"provider:cmf…"`). Empty string against legacy fallbacks that
+     * didn't synthesise a catalog id.
+     */
+    id: string;
+    /**
+     * Lowercase provider id: `"openai"`, `"anthropic"`, `"google"`,
+     * `"azure-openai"`. Empty string against legacy runners that don't
+     * report usage data — SDK callers use that as the "no usage data"
+     * signal.
+     */
+    provider: string;
+    /**
+     * The model id the platform actually sent to the provider (e.g.
+     * `"gpt-5.4-mini"`, `"claude-opus-4-7"`, `"gemini-2.5-pro"`).
+     */
+    vendorModelId: string;
+    /**
+     * `"off" | "low" | "medium" | "high"`. Omitted when the provider
+     * doesn't expose a reasoning-level knob or the run didn't request
+     * one.
+     */
+    reasoningEffort?: string;
+}
 interface RunResult {
     runId: string;
     text: string;
     events: RunEvent[];
+    /**
+     * Per-run token totals from the terminal event. Undefined against
+     * MANTYX servers older than 2026-09 (the "no usage data" signal is
+     * `result.model?.provider` being empty / undefined). See
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     */
+    tokens?: RunTokenUsage;
+    /**
+     * Total `engine.completeTurn(...)` invocations for the run,
+     * including the failing call when a run errored mid-loop. A
+     * single-shot run reports `1`; a tool loop is `>= 2`. Undefined
+     * against legacy MANTYX servers.
+     */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface RunEventBase {
     seq: number;
@@ -1031,11 +1194,44 @@ 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;
     text?: string;
     error?: string;
+    /**
+     * Per-run token totals. Present against MANTYX ≥ 2026-09 — see
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     */
+    tokens?: RunTokenUsage;
+    /** Total model invocations for the run. See {@link RunResult.turns}. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface ErrorEvent extends RunEventBase {
     type: "error";
@@ -1074,12 +1270,24 @@ interface ErrorEvent extends RunEventBase {
      * Informational; the SDK still owns the actual retry decision.
      */
     retryable?: boolean;
+    /**
+     * Per-run token totals. Present against MANTYX ≥ 2026-09 — see
+     * {@link RunTokenUsage} and `docs/agent-runs-protocol.md` §7.1.
+     * The pipeline counts the failing model call too, so a run that
+     * threw on the first turn reports `turns: 1` with that call's
+     * tokens already aggregated.
+     */
+    tokens?: RunTokenUsage;
+    /** Total model invocations for the run, including the failing call. */
+    turns?: number;
+    /** Resolved model that executed the run. See {@link RunModelInfo}. */
+    model?: RunModelInfo;
 }
 interface CancelledEvent extends RunEventBase {
     type: "cancelled";
     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;
 });
@@ -1222,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;
@@ -1230,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<{
@@ -1280,4 +1495,4 @@ interface LocalHandlers {
  */
 declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
 
-export { type RunResult as $, type A2AToolRef as A, MantyxOAuthError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxParseError as F, type MantyxPluginToolRef as G, MantyxRunError as H, type MantyxRunErrorInit as I, MantyxScopeError as J, MantyxToolError as K, type LocalA2ATool as L, MantyxClient as M, type MantyxToolRef as N, type McpToolRef as O, type ModelCatalog as P, type ModelInfo as Q, type ReasoningLevel as R, type OAuthToken as S, type ToolRef as T, type OutputSchema as U, type RefreshOptions as V, type RefreshTokenSourceOptions as W, type ResultEvent as X, type RevokeOptions as Y, type RunEvent as Z, type RunEventBase as _, AgentSession as a, type RunSpec as a0, type ServerToolResultEvent as a1, type SessionInfo as a2, type SessionSpec as a3, type ThinkingDeltaEvent as a4, type TokenRequestReason as a5, type TokenSource as a6, type ToolBudget as a7, type ToolBudgetExceededEvent as a8, type ToolBudgets as a9, type ZodLikeObject as aa, defineLocalA2A as ab, defineLocalMcp as ac, defineLocalTool as ad, isLocalA2ATool as ae, isLocalMcpServer as af, isLocalTool as ag, mantyxA2A as ah, mantyxMcp as ai, mantyxPluginTool as aj, mantyxTool as ak, parseRunOutput as al, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, DEFAULT_OAUTH_BASE_URL as e, DEFAULT_REFRESH_SKEW_MS as f, type DefineLocalA2AOptions as g, type DefineLocalMcpOptions as h, type DefineLocalToolOptions as i, type LocalHandlers as j, type LocalMcpHttpTransport as k, type LocalMcpServer as l, type LocalMcpStdioTransport as m, type LocalTool as n, type LocalToolCallEvent as o, type LocalToolResultInEvent as p, type LoopDetectedEvent as q, type LoopDetection as r, type MantyxA2AOptions as s, MantyxAuthError as t, type MantyxClientOptions as u, MantyxError as v, type MantyxMcpOptions as w, MantyxNetworkError as x, MantyxOAuthClient as y, type MantyxOAuthClientOptions as z };
+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 };