Runtime Limits

A3S Code provides a set of runtime limit mechanisms to prevent agents from looping indefinitely, hanging, or consuming excessive resources. All limits are configured through SessionOptions without modifying core logic.

Agent Execution
  ├─ max_tool_rounds      ← Tool call round cap (default 50)
  ├─ tool_timeout_ms      ← Per-tool execution timeout
  ├─ circuit_breaker      ← Break on consecutive LLM failures
  ├─ max_parse_retries    ← Tool argument parse error retry cap
  ├─ continuation_turns   ← Continuation injection cap
  ├─ retry_config         ← LLM API exponential backoff retry
  └─ auto_compact         ← Context window auto-compaction

Tool Round Cap

max_tool_rounds limits the total tool call rounds within a single send() / stream(). When the limit is reached, the agent stops and returns the current result.

const session = agent.session('/project', {
  maxToolRounds: 20,  // default 50
});

session = agent.session("/project", max_tool_rounds=20)  # default 50

Tool Execution Timeout

tool_timeout_ms sets a timeout for each individual tool call. A timeout does not crash the session — the timeout result is returned to the LLM as an error, and the LLM can choose to retry or try a different approach.

const session = agent.session('/project', {
  toolTimeoutMs: 10_000,
});

session = agent.session("/project", tool_timeout_ms=10_000)

On timeout, the agent receives a tool result like:

Tool 'bash' timed out after 10000ms

Circuit Breaker

circuit_breaker_threshold controls how many consecutive LLM API failures trigger an abort (non-streaming mode). Prevents the agent from retrying indefinitely when the API is unstable.

const session = agent.session('/project', {
  circuitBreakerThreshold: 5,
});

session = agent.session("/project", circuit_breaker_threshold=5)

LLM API Retry Config

A3S Code has built-in exponential backoff retry with Retry-After header support. By default it retries 429 (rate limit), 500, 502, 503, and 529 (Anthropic overload).

const session = agent.session('/project', {
  retryConfig: {
    maxRetries: 5,
    baseDelayMs: 500,
    maxDelayMs: 60_000,
  },
});

session = agent.session("/project", retry_config={
    "max_retries": 5,
    "base_delay_ms": 500,
    "max_delay_ms": 60_000,
})

Backoff formula: delay = base_delay × 2^attempt, capped at max_delay, with ±25% jitter. If the response contains a Retry-After header, that value takes priority.

To disable retries:

Parse Error Retries

LLMs occasionally return malformed tool arguments. max_parse_retries controls how many consecutive parse errors are tolerated before aborting (default 2).

const session = agent.session('/project', {
  maxParseRetries: 3,
});

session = agent.session("/project", max_parse_retries=3)

Continuation Cap

When the LLM stops calling tools before the task is complete, A3S Code automatically injects a continuation message to keep execution going. max_continuation_turns limits how many times this can happen (default 3).

const session = agent.session('/project', {
  continuationEnabled: true,
  maxContinuationTurns: 5,
});

session = agent.session("/project",
    continuation_enabled=True,
    max_continuation_turns=5,
)

Auto-Compaction

When context window usage exceeds the threshold, A3S Code automatically calls the LLM to summarize history, preventing context overflow.

const session = agent.session('/project', {
  autoCompact: true,
  autoCompactThreshold: 0.75,
});

session = agent.session("/project",
    auto_compact=True,
    auto_compact_threshold=0.75,
)

See Auto-Compact Example for a full walkthrough.

Combining Limits

Recommended production combination:

const session = agent.session('/project', {
  maxToolRounds: 30,
  toolTimeoutMs: 15_000,
  circuitBreakerThreshold: 3,
  maxParseRetries: 2,
  continuationEnabled: true,
  maxContinuationTurns: 3,
  autoCompact: true,
  autoCompactThreshold: 0.80,
});

session = agent.session("/project",
    max_tool_rounds=30,
    tool_timeout_ms=15_000,
    circuit_breaker_threshold=3,
    max_parse_retries=2,
    continuation_enabled=True,
    max_continuation_turns=3,
    auto_compact=True,
    auto_compact_threshold=0.80,
)

API Reference

RetryConfig