@mantyx/sdk 0.7.0 → 0.9.0

package/dist/{client-ChxfhYBJ.d.ts → client-CeWCSsmD.d.ts}

@@ -39,11 +39,35 @@ type ZodLikeObject = z.ZodType<Record<string, unknown>> & {
  * integer in `0..100` (where `0` explicitly disables provider thinking).
  */
 type ReasoningLevel = "off" | "low" | "medium" | "high" | number;
+/**
+ * Either a Zod schema (auto-converted to JSON Schema by the SDK) or a
+ * pre-shaped JSON Schema object. Used for both `parameters` and the new
+ * `outputSchema` field — same conversion path either way.
+ */
+type LocalToolSchemaInput = ZodLikeObject | Record<string, unknown>;
 interface LocalTool<TArgs = Record<string, unknown>> {
     readonly kind: "local";
     readonly name: string;
     readonly description: string;
     readonly parameters: ZodLikeObject | undefined;
+    /**
+     * Optional JSON Schema (or Zod schema, auto-converted) describing the
+     * tool's structured return value. Forwarded to providers with per-tool
+     * response schemas (Gemini's `responseJsonSchema` on the
+     * FunctionDeclaration); other engines surface it through the description
+     * and rely on host-side validation. The model uses it to plan follow-up
+     * arguments more reliably. See `docs/wire-protocol.md` §3.1.
+     */
+    readonly outputSchema: LocalToolSchemaInput | undefined;
+    /**
+     * When `true`, MANTYX appends a stable hint to the model-facing
+     * description telling the model not to re-issue calls while a previous
+     * invocation is still pending. Useful for tools that may yield a
+     * `pending` / status response and the SDK polls on its own; without the
+     * hint, models routinely fire repeat calls and waste turns. Pure
+     * declarative — MANTYX does not change scheduling.
+     */
+    readonly longRunning: boolean;
     readonly execute: (args: TArgs) => Promise<string> | string;
 }
 interface DefineLocalToolOptions<T extends ZodLikeObject | undefined> {
@@ -51,6 +75,17 @@ interface DefineLocalToolOptions<T extends ZodLikeObject | undefined> {
     name: string;
     description?: string;
     parameters?: T;
+    /**
+     * Optional JSON Schema (or Zod schema) describing the tool's return
+     * value. See {@link LocalTool.outputSchema}.
+     */
+    outputSchema?: LocalToolSchemaInput;
+    /**
+     * Annotate the tool as long-running so the model doesn't double-call
+     * while a previous invocation is still pending. See
+     * {@link LocalTool.longRunning}.
+     */
+    longRunning?: boolean;
     execute: (args: T extends ZodLikeObject ? z.infer<T> : Record<string, unknown>) => Promise<string> | string;
 }
 declare function defineLocalTool<T extends ZodLikeObject | undefined>(opts: DefineLocalToolOptions<T>): LocalTool;
@@ -371,6 +406,44 @@ interface AgentSpecBase {
      * ajv schema). See `docs/wire-protocol.md` §7.
      */
     outputSchema?: OutputSchema;
+    /**
+     * Loop-detection guard. Tracks an order-invariant `(toolName, args)`
+     * signature for every assistant turn that emits one or more tool calls;
+     * when the same signature repeats consecutively the pipeline first injects
+     * a steering nudge ("either deliver a final answer or change strategy")
+     * and eventually forces a tools-disabled finalise turn.
+     *
+     * Pass an object to override the default thresholds, or `false` to
+     * explicitly disable the guard for this run / session. When omitted, the
+     * MANTYX runtime defaults apply (`{ consecutiveThreshold: 3,
+     * hardCutoffThreshold: 6 }`). See `docs/agent-runs-protocol.md` §4.6.
+     *
+     * Each intervention emits an observability-only `loop_detected` SSE event
+     * the SDK surfaces on the run-event stream (`tools` lists the looping
+     * batch; `hardCutoff: false` is the soft nudge round, `true` is the
+     * forced finalise). The synthetic skip + nudge are emitted on the normal
+     * `tool_result` / `assistant_delta` channels — the SDK does not need to
+     * act on the event itself.
+     */
+    loopDetection?: LoopDetection | false;
+    /**
+     * Per-tool call caps enforced over the **lifetime of the run** (across
+     * every LLM turn). Calls under the cap run normally; calls past the cap
+     * are intercepted before execution and returned to the model as a
+     * synthetic "budget exceeded — pivot or finalize" tool result.
+     *
+     * Keys are the model-facing tool names (the same string on
+     * `local_tool_call.name`); values are `{ maxCalls: number }`. `maxCalls:
+     * 0` disables the tool entirely (the first attempt returns the synthetic
+     * body). Budgets are **per-tool, not pooled**.
+     *
+     * Pass `{}` to start from a clean slate (no defaults applied on top —
+     * useful for runs that intentionally want unbounded research). Omit
+     * entirely to keep the runtime defaults. Each interception emits an
+     * observability-only `tool_budget_exceeded` SSE event. See
+     * `docs/agent-runs-protocol.md` §4.7.
+     */
+    toolBudgets?: ToolBudgets;
     /**
      * Flat string→string KV carried alongside the run / session for
      * observability. Use it to tag runs with your own application identifiers
@@ -409,6 +482,50 @@ interface OutputSchema {
     /** Required. JSON Schema describing the final assistant text. Root must be a JSON object. */
     schema: Record<string, unknown>;
 }
+/**
+ * Loop-detection thresholds. See {@link AgentSpecBase.loopDetection} for the
+ * full semantics. Pass `false` (instead of an object) to disable the guard.
+ *
+ * Both fields are optional; omitted ones inherit the MANTYX runtime
+ * defaults (`consecutiveThreshold: 3`, `hardCutoffThreshold: 6`).
+ */
+interface LoopDetection {
+    /**
+     * Number of identical consecutive tool-call batches that triggers the
+     * **soft nudge** — the pipeline injects a steering message ("either
+     * deliver a final answer or change strategy"). Default `3`. Must be
+     * `>= 2` (one identical batch is just a single tool call, not a loop).
+     * Server-side upper bound: `100`.
+     */
+    consecutiveThreshold?: number;
+    /**
+     * Number of identical consecutive tool-call batches that triggers the
+     * **hard cutoff** — the pipeline forces a tools-disabled finalise turn.
+     * Default `6`. Must be strictly greater than `consecutiveThreshold` (so
+     * the soft nudge has a chance to land). Server-side upper bound: `100`.
+     */
+    hardCutoffThreshold?: number;
+}
+/**
+ * Per-tool call cap. See {@link AgentSpecBase.toolBudgets} for the full
+ * semantics.
+ */
+interface ToolBudget {
+    /**
+     * Hard cap on executed calls per run. `0` disables the tool entirely
+     * (every attempt returns the synthetic "budget exceeded" body on the
+     * first try). Server-side upper bound: `1000` (functionally unlimited;
+     * the in-runtime `maxToolTurns: 100` fires first).
+     */
+    maxCalls: number;
+}
+/**
+ * Map of model-facing tool name → cap. See
+ * {@link AgentSpecBase.toolBudgets}. Pass an empty object (`{}`) to start
+ * from a clean slate (no runtime defaults applied on top); omit the field
+ * entirely to keep the defaults.
+ */
+type ToolBudgets = Record<string, ToolBudget>;
 interface RunResult {
     runId: string;
     text: string;
@@ -492,6 +609,43 @@ interface LocalToolResultInEvent extends RunEventBase {
     result?: string;
     error?: string;
 }
+/**
+ * Observability event fired when the loop-detection guard intervenes.
+ * The synthetic skip + steering nudge are emitted on the normal
+ * `tool_result` / `assistant_delta` channels; this event lets the SDK
+ * render a status note (`looping — nudged` / `looping — gave up`).
+ *
+ * `hardCutoff: false` is the soft nudge round; `true` is the forced
+ * finalise. The same run may emit one of each.
+ */
+interface LoopDetectedEvent extends RunEventBase {
+    type: "loop_detected";
+    /** Length of the identical-batch streak that just tripped the threshold. */
+    consecutiveCount: number;
+    /** `false` for the soft nudge round; `true` once the pipeline forces finalisation. */
+    hardCutoff: boolean;
+    /** Names of the tool calls in the looping batch (no args). */
+    tools: string[];
+}
+/**
+ * Observability event fired when a tool-budget interception happens. The
+ * synthetic "budget exceeded — pivot or finalize" tool result lands on the
+ * normal `tool_result` channel before this event fires; the SDK uses this
+ * event to render UI banners (`memory budget exhausted` etc.) without
+ * re-parsing tool-result bodies.
+ */
+interface ToolBudgetExceededEvent extends RunEventBase {
+    type: "tool_budget_exceeded";
+    /** Logical tool name (matches the key in `spec.toolBudgets`). */
+    tool: string;
+    /** Configured cap. */
+    maxCalls: number;
+    /**
+     * 1-based count of attempts to call this tool over the run lifetime.
+     * Always strictly greater than `maxCalls`.
+     */
+    callIndex: number;
+}
 interface ResultEvent extends RunEventBase {
     type: "result";
     subtype: string;
@@ -507,7 +661,7 @@ interface CancelledEvent extends RunEventBase {
     type: "cancelled";
     reason?: string;
 }
-type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
+type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | LoopDetectedEvent | ToolBudgetExceededEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
     type: string;
     [key: string]: unknown;
 });
@@ -599,12 +753,25 @@ declare class AgentSession {
          * and does not mutate the session's stored value.
          */
         outputSchema?: OutputSchema;
+        /**
+         * Per-message override for `loopDetection`. Applies only to this run
+         * and does not mutate the session's stored value. Pass `false` to
+         * disable the guard for this single turn.
+         */
+        loopDetection?: LoopDetection | false;
+        /**
+         * Per-message override for `toolBudgets`. Applies only to this run
+         * and does not mutate the session's stored value.
+         */
+        toolBudgets?: ToolBudgets;
     }): Promise<RunResult>;
     stream(prompt: string, opts?: {
         signal?: AbortSignal;
         metadata?: Record<string, string>;
         reasoningLevel?: ReasoningLevel;
         outputSchema?: OutputSchema;
+        loopDetection?: LoopDetection | false;
+        toolBudgets?: ToolBudgets;
     }): AsyncGenerator<RunEvent, void, void>;
     private buildSessionMessageBody;
     history(): Promise<Array<{
@@ -655,4 +822,4 @@ interface LocalHandlers {
  */
 declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
 
-export { type A2AToolRef as A, type RunSpec as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, type SessionInfo as F, type SessionSpec as G, type ThinkingDeltaEvent as H, defineLocalA2A as I, defineLocalMcp as J, defineLocalTool as K, type LocalA2ATool as L, MantyxClient as M, isLocalA2ATool as N, type OutputSchema as O, isLocalMcpServer as P, isLocalTool as Q, type ReasoningLevel as R, type ServerToolResultEvent as S, type ToolRef as T, mantyxA2A as U, mantyxMcp as V, mantyxPluginTool as W, mantyxTool as X, parseRunOutput as Y, type ZodLikeObject as Z, AgentSession as a, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, type DefineLocalA2AOptions as e, type DefineLocalMcpOptions as f, type DefineLocalToolOptions as g, type LocalHandlers as h, type LocalMcpHttpTransport as i, type LocalMcpServer as j, type LocalMcpStdioTransport as k, type LocalTool as l, type LocalToolCallEvent as m, type LocalToolResultInEvent as n, type MantyxA2AOptions as o, type MantyxClientOptions as p, type MantyxMcpOptions as q, type MantyxPluginToolRef as r, type MantyxToolRef as s, type McpToolRef as t, type ModelCatalog as u, type ModelInfo as v, type ResultEvent as w, type RunEvent as x, type RunEventBase as y, type RunResult as z };
+export { mantyxMcp as $, type A2AToolRef as A, type RunEventBase as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, type RunResult as F, type RunSpec as G, type SessionInfo as H, type SessionSpec as I, type ThinkingDeltaEvent as J, type ToolBudget as K, type LocalA2ATool as L, MantyxClient as M, type ToolBudgetExceededEvent as N, type OutputSchema as O, type ToolBudgets as P, defineLocalA2A as Q, type ReasoningLevel as R, type ServerToolResultEvent as S, type ToolRef as T, defineLocalMcp as U, defineLocalTool as V, isLocalA2ATool as W, isLocalMcpServer as X, isLocalTool as Y, type ZodLikeObject as Z, mantyxA2A as _, AgentSession as a, mantyxPluginTool as a0, mantyxTool as a1, parseRunOutput as a2, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, type DefineLocalA2AOptions as e, type DefineLocalMcpOptions as f, type DefineLocalToolOptions as g, type LocalHandlers as h, type LocalMcpHttpTransport as i, type LocalMcpServer as j, type LocalMcpStdioTransport as k, type LocalTool as l, type LocalToolCallEvent as m, type LocalToolResultInEvent as n, type LoopDetectedEvent as o, type LoopDetection as p, type MantyxA2AOptions as q, type MantyxClientOptions as r, type MantyxMcpOptions as s, type MantyxPluginToolRef as t, type MantyxToolRef as u, type McpToolRef as v, type ModelCatalog as w, type ModelInfo as x, type ResultEvent as y, type RunEvent as z };

package/dist/index.cjs

@@ -125,6 +125,8 @@ function defineLocalTool(opts) {
     name: opts.name,
     description: opts.description ?? "",
     parameters: opts.parameters,
+    outputSchema: opts.outputSchema,
+    longRunning: opts.longRunning ?? false,
     execute: opts.execute
   };
 }
@@ -976,6 +978,12 @@ var AgentSession = class {
     if (opts.outputSchema !== void 0) {
       body.outputSchema = normalizeOutputSchema(opts.outputSchema);
     }
+    if (opts.loopDetection !== void 0) {
+      body.loopDetection = normalizeLoopDetection(opts.loopDetection);
+    }
+    if (opts.toolBudgets !== void 0) {
+      body.toolBudgets = normalizeToolBudgets(opts.toolBudgets);
+    }
     return body;
   }
   async history() {
@@ -1010,6 +1018,12 @@ function serializeAgentSpec(spec, extra = {}) {
   if (spec.outputSchema !== void 0) {
     body.outputSchema = normalizeOutputSchema(spec.outputSchema);
   }
+  if (spec.loopDetection !== void 0) {
+    body.loopDetection = normalizeLoopDetection(spec.loopDetection);
+  }
+  if (spec.toolBudgets !== void 0) {
+    body.toolBudgets = normalizeToolBudgets(spec.toolBudgets);
+  }
   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;
@@ -1028,7 +1042,9 @@ function serializeToolRefs(tools) {
           kind: "local",
           name: t.name,
           description: t.description,
-          parameters: toToolParametersWire(t.parameters)
+          parameters: toToolParametersWire(t.parameters),
+          ...t.outputSchema !== void 0 ? { outputSchema: toToolParametersWire(t.outputSchema) } : {},
+          ...t.longRunning ? { longRunning: true } : {}
         };
       case "a2a":
         return {
@@ -1165,6 +1181,93 @@ function normalizeOutputSchema(value) {
   }
   return out;
 }
+var LOOP_DETECTION_THRESHOLD_MAX = 100;
+function normalizeLoopDetection(value) {
+  if (value === false) return false;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MantyxError(
+      `loopDetection must be an object or the literal \`false\`, got ${JSON.stringify(value)}`
+    );
+  }
+  const out = {};
+  if (value.consecutiveThreshold !== void 0) {
+    out.consecutiveThreshold = assertThreshold(
+      "loopDetection.consecutiveThreshold",
+      value.consecutiveThreshold,
+      2
+    );
+  }
+  if (value.hardCutoffThreshold !== void 0) {
+    out.hardCutoffThreshold = assertThreshold(
+      "loopDetection.hardCutoffThreshold",
+      value.hardCutoffThreshold,
+      3
+    );
+  }
+  if (typeof out.consecutiveThreshold === "number" && typeof out.hardCutoffThreshold === "number" && out.hardCutoffThreshold <= out.consecutiveThreshold) {
+    throw new MantyxError(
+      `loopDetection.hardCutoffThreshold (${out.hardCutoffThreshold}) must be strictly greater than loopDetection.consecutiveThreshold (${out.consecutiveThreshold})`
+    );
+  }
+  return out;
+}
+function assertThreshold(label, value, min) {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new MantyxError(`${label} must be an integer, got ${JSON.stringify(value)}`);
+  }
+  if (value < min) {
+    throw new MantyxError(`${label} must be >= ${min}, got ${value}`);
+  }
+  if (value > LOOP_DETECTION_THRESHOLD_MAX) {
+    throw new MantyxError(
+      `${label} must be <= ${LOOP_DETECTION_THRESHOLD_MAX} (server-enforced), got ${value}`
+    );
+  }
+  return value;
+}
+var TOOL_BUDGETS_MAX_ENTRIES = 32;
+var TOOL_BUDGET_MAX_NAME_LEN = 120;
+var TOOL_BUDGET_MAX_CALLS = 1e3;
+function normalizeToolBudgets(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MantyxError(
+      `toolBudgets must be an object of shape { [name]: { maxCalls } }, got ${JSON.stringify(value)}`
+    );
+  }
+  const keys = Object.keys(value);
+  if (keys.length > TOOL_BUDGETS_MAX_ENTRIES) {
+    throw new MantyxError(
+      `toolBudgets has ${keys.length} entries; the server enforces a ${TOOL_BUDGETS_MAX_ENTRIES}-entry limit`
+    );
+  }
+  const out = {};
+  for (const key of keys) {
+    if (typeof key !== "string" || key.length < 1 || key.length > TOOL_BUDGET_MAX_NAME_LEN) {
+      throw new MantyxError(
+        `toolBudgets keys must be 1..${TOOL_BUDGET_MAX_NAME_LEN}-char strings, got ${JSON.stringify(key)}`
+      );
+    }
+    const entry = value[key];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new MantyxError(
+        `toolBudgets[${JSON.stringify(key)}] must be an object { maxCalls }, got ${JSON.stringify(entry)}`
+      );
+    }
+    const maxCalls = entry.maxCalls;
+    if (typeof maxCalls !== "number" || !Number.isFinite(maxCalls) || !Number.isInteger(maxCalls) || maxCalls < 0) {
+      throw new MantyxError(
+        `toolBudgets[${JSON.stringify(key)}].maxCalls must be a non-negative integer, got ${JSON.stringify(maxCalls)}`
+      );
+    }
+    if (maxCalls > TOOL_BUDGET_MAX_CALLS) {
+      throw new MantyxError(
+        `toolBudgets[${JSON.stringify(key)}].maxCalls must be <= ${TOOL_BUDGET_MAX_CALLS} (server-enforced), got ${maxCalls}`
+      );
+    }
+    out[key] = { maxCalls };
+  }
+  return out;
+}
 function parseRunOutput(result, validator) {
   let parsed;
   try {
@@ -1194,7 +1297,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.7.0";
+var SDK_VERSION = "0.9.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentSession,