1. Full Configuration Options Reference
| Parameter | Type | Default | Description |
|---|---|---|---|
| agentId | string | "agent_run" | Unique deterministic slug for tracing multi-agent sub-trees. |
| agentName | string | "default-agent" | Human-readable agent identifier shown in cloud telemetry. |
| maxRepeatCalls | number | 5 | Trips when identical SHA-256 argument hashes repeat N times within time window. |
| maxCostDollar | number | $2.00 | Dollar spending ceiling for a single agent execution run. |
| maxDepth | number | 15 | Maximum recursion step depth before tripping depth ceiling. |
| maxNoProgressTurns | number | 3 | Trips when N consecutive turns produce identical output state hashes. |
| autoFallbackCheaperModel | boolean | true | Automatically switch model to cheaper tier on soft trip before terminating. |
| apiKey | string | undefined | Moven hosted telemetry API Key (`moven_sk_live_...`). |
| maxToolCallHistory | number | 500 | Bounded tool-call ledger retention — long runs never grow without limit. |
| maxPromptHistory | number | 200 | Bounded prompt-history retention (newest turns kept). |
| telemetryFailureThreshold | number | 5 | Consecutive telemetry failures before outbound export pauses (self-protection). |
| telemetryCooldownMs | number | 60000 | Fail-fast window while telemetry is paused. In-process protection is unaffected. |
| humanAttestationWindowMs | number | 300000 | How long a mid-run user message attests following calls as human-directed (loop heuristics relaxed). |
| maxHumanAttestedStagnantSteps | number | 12 | Stagnation ceiling for human-attested calls with identical results (waste backstop). |
2. Complete `moven.config.ts` Code Example
Below is a complete enterprise-grade moven.config.ts configuration example initializing circuit breaker rules, provider mappings, and hallucination alerts:
import { createMovenCircuitBreaker } from 'moven-sdk'; export const movenCircuitBreaker = createMovenCircuitBreaker({ // Production Agent Identity agentId: 'agent_inventory_prod_01', agentName: 'inventory_production_agent', framework: 'LangGraph / LangChain', version: '1.2.0', tags: ['production', 'e-commerce'], // Rule 01: Intercept tool called 5x in 60s with identical arguments maxRepeatCalls: 5, repeatTimeWindowMs: 60000, // Rule 02: Strict Dollar Cost Ceiling ($2.00 max per agent run) maxCostDollar: 2.00, // Rule 03: Recursion & Depth Limit (Max 15 sub-agent steps) maxDepth: 15, // Rule 04: No-Progress State Hash Shield (3 consecutive identical turn outputs) maxNoProgressTurns: 3, // Rule 05: Cheaper Model Fallback provider: 'openai', currentModel: 'gpt-4o', cheaperModel: 'gpt-4o-mini', autoFallbackCheaperModel: true, // Callbacks onHallucination: ({ agentName, reason, toolName }) => { console.warn(`[Moven Alert] Agent '${agentName}' hallucination on tool '${toolName}': ${reason}`); }, // Telemetry API Key apiKey: process.env.MOVEN_API_KEY,});
3. MovenRunState
The in-memory run container. Tracks tool call logs, cumulative prompt / completion / total tokens, cumulative cost, depth, state hashes and checkpoint snapshots for every run. Key methods: recordToolCall(), recordToolResult(), recordStepTokens(), getMetrics() and generateWorkflowGraph().
4. MovenReporter
Async telemetry dispatcher with retry + backoff to api.moven.dev/events. reportRunStart() syncs cloud policy, reportTrace() persists completed runs with full token & cost metrics, and reportKillEvent() transmits circuit breaker trips.
5. MovenKillError & Events
Thrown when a heuristic trips. Carries heuristic, reason, toolName, toolArgs and full metrics (cost, tokens, repeat count, depth). Catch it in your agent loop to trigger graceful recovery.
6. Pre-Trip Model Warnings (any SDK)
One call before a heuristic trips, the breaker queues a warning. Inject it into your next model invocation so the LLM can change strategy instead of being killed. Works with OpenAI SDK, Anthropic, CrewAI, AutoGen, LlamaIndex and raw loops — warnModel() is pure, drains exactly once, and is a passthrough when nothing is queued.
const breaker = createMovenCircuitBreaker({ agentName: 'research-agent', maxRepeatCalls: 3, warnBeforeTrip: true });const tools = breaker.wrapTools({ search_web, fetch_page }).tools; for (const step of steps) { const messages = breaker.warnModel([...history, { role: 'user', content: step.prompt }]); const res = await openai.chat.completions.create({ model: 'gpt-4o', messages }); // ... execute tool calls through the wrapped tools}
7. createMovenLangGraphGuard (LangGraph / LangChain)
One guard object wiring both sides of the loop: wrapModel(llm) auto-injects pre-trip warnings into every .invoke / .stream / .bindTools call; wrapTools(tools)provides interception, kill, pause & fallback. Also exports withMovenWarnings() and wrapModelWithMoven().
import { createMovenLangGraphGuard } from 'moven-sdk';import { ChatOpenAI } from '@langchain/openai'; const guard = createMovenLangGraphGuard({ agentName: 'research-agent', maxRepeatCalls: 3 }); const llm = guard.wrapModel(new ChatOpenAI({ model: 'gpt-4o' })); // warnings auto-injectedconst tools = guard.wrapTools({ search_web, fetch_page }).tools; // interception + kill
8. User-Intent Attestation — “Allow Repeat Tool Calls If User Asks”
The instruction-intent classifier decides whether a user message actually licenses repetition (lexicon features, weighted scoring, count extraction, topic attribution — deterministic, <0.1ms, no ML deps). When enabled (Agent Settings → Loop Protection), “search tesla revenue 5 times” allows exactly 5 identical searches — the 6th trips user_directed_ceiling. Hard ceilings (cost / depth / burn guard) are never relaxed.
const guard = createMovenLangGraphGuard({ enableUserIntentAttestation: true, // Agent Settings toggle (off = NOT RECOMMENDED strict mode) humanAttestationWindowMs: 300000, // how long a directive licenses repetition maxHumanAttestedStagnantSteps: 12, // waste backstop when no count is given intentDirectiveThreshold: 0.5, // classifier strictness (0..1)}); // Mid-run user messages attest automatically; explicit API:guard.state.recordUserInstruction('search tesla revenue 5 times');