runtime-smoke-20260710143823/runtime-analysis/SPECIFICATION.md

Agent Runtime Specification

1. MiniMax Connection Specification

1.1 Connection Pool

Property	Specification
Pool Size	Configurable, default 100
Connection Timeout	30 seconds
Keep-Alive	Enabled by default
Idle Timeout	60 seconds
Max Routes Per Route	50

1.2 Request Format

{
  "model": "string (required)",
  "messages": [
    {
      "role": "string (required)",
      "content": "string (required)"
    }
  ],
  "temperature": "number (0-2, optional)",
  "max_tokens": "integer (optional)",
  "stream": "boolean (optional, default false)"
}

1.3 Response Format

{
  "id": "string",
  "model": "string",
  "choices": [
    {
      "index": "integer",
      "message": {
        "role": "string",
        "content": "string"
      },
      "finish_reason": "string"
    }
  ],
  "usage": {
    "prompt_tokens": "integer",
    "completion_tokens": "integer",
    "total_tokens": "integer"
  }
}

---

2. Output Contract Specification

2.1 Contract Version 1.0

Field	Type	Required	Constraints
content	string	Yes	0 ≤ length ≤ 128000
model	string	Yes	Non-empty
usage	object	Yes	Contains prompt_tokens, completion_tokens, total_tokens
finish_reason	enum	Yes	One of: stop, length, content_filter, tool_calls
tool_calls	array	No	Array of tool call objects
citations	array	No	Array of citation objects
metadata	object	No	Arbitrary key-value pairs

2.2 Validation Rules

1. Schema Validation: All required fields must be present
2. Type Validation: Field types must match specification
3. Range Validation: Numeric values within bounds
4. Enum Validation: Enumerated values from allowed set

2.3 Validation Error Response

{
  "error": {
    "code": "CONTRACT_VIOLATION",
    "message": "string",
    "violations": [
      {
        "field": "string",
        "expected": "string",
        "actual": "string"
      }
    ]
  }
}

---

3. Retry Mechanism Specification

3.1 Retry Policy

Condition	Action
Network timeout	Retry
HTTP 408	Retry
HTTP 429	Retry with longer backoff
HTTP 5xx	Retry
HTTP 400	Do not retry
HTTP 401	Do not retry
HTTP 403	Do not retry
Validation error	Do not retry

3.2 Backoff Algorithm

delay = min(initial_delay * (multiplier ^ attempt) + jitter, max_delay)

where:
  initial_delay = 1000ms
  multiplier = 2.0
  jitter = random(-10%, +10%)
  max_delay = 30000ms

3.3 Circuit Breaker States

State	Condition	Behavior
CLOSED	Normal operation	All requests pass
OPEN	Failure rate > 50% in 10s	All requests fail fast
HALF_OPEN	After 10s in OPEN	Allow 5 test requests

---

4. Observation Points Specification

4.1 Trace Spans

Span Name	Parent	Attributes
agent-runtime-request	Root	request_id, model
connection-acquire	agent-runtime-request	pool_name, wait_time
request-build	agent-runtime-request	payload_size
api-call	agent-runtime-request	endpoint, status_code
retry-attempt-N	api-call	attempt_num, error
response-parse	agent-runtime-request	response_size
contract-validate	agent-runtime-request	result, violations
response-emit	agent-runtime-request	output_size

4.2 Metrics

Metric	Type	Labels	Description
runtime_requests_total	Counter	model, status	Total requests
runtime_request_duration_seconds	Histogram	model	Request latency
runtime_connections_active	Gauge	pool_name	Active connections
runtime_connections_wait_seconds	Histogram	pool_name	Wait time
runtime_retries_total	Counter	model, error_type	Retry count
runtime_contract_validations_total	Counter	result	Validation count
runtime_circuit_breaker_state	Gauge	circuit_name	CB state (0/1/2)

4.3 Log Events

Event	Level	Fields
request_initiated	INFO	request_id, model, timestamp
request_completed	INFO	request_id, duration_ms, tokens_used
request_failed	ERROR	request_id, error_code, error_message
retry_triggered	WARN	request_id, attempt, error_type, delay_ms
circuit_opened	ERROR	circuit_name, failure_rate
circuit_closed	INFO	circuit_name
contract_violation	ERROR	request_id, violations[]

---

5. Integration Contract

5.1 Component Dependencies

Client
  └── AgentRuntime
        ├── MiniMaxConnector
        │     └── ConnectionPool
        ├── OutputContract
        │     ├── SchemaValidator
        │     └── TypeCoercer
        ├── RetryMechanism
        │     ├── RetryPolicy
        │     ├── BackoffCalculator
        │     └── CircuitBreaker
        └── Observability
              ├── Tracer
              ├── MetricsCollector
              └── LogEmitter

5.2 Error Propagation

Source	Error Type	Propagation
MiniMaxConnector	ConnectionError	RetryMechanism
MiniMaxConnector	TimeoutError	RetryMechanism
MiniMaxConnector	AuthError	Client (no retry)
OutputContract	ValidationError	Client (no retry)
CircuitBreaker	OpenError	Client (no retry)

---

Specification Version: 1.0 Last Updated: 2026-07-10