fix(aws): unwrap doubly-encoded JSON tool arguments from Nova Sonic

[rililinx]

Summary

Nova Sonic 2 (AWS Bedrock) occasionally delivers toolUse.content as a doubly-encoded JSON string — a JSON string whose parsed value is itself another JSON string containing a JSON object. This caused prepare_function_arguments to receive a str instead of a dict, crashing with:

TypeError: string indices must be integers, not 'str'  (livekit/agents/llm/utils.py:404)

Root cause

In _handle_tool_output_content_event, args is passed directly to FunctionCall(arguments=args). When Nova Sonic double-encodes the arguments, pydantic_core.from_json() downstream returns a Python str instead of a dict, then indexing with a param name string fails.

Fix

Peel off one encoding layer when the outer JSON parse yields a string — but only if that inner string is itself a valid JSON object (dict). This is the critical guard:

• Double-encoded object (bug case): "\"{ \\\"date\\\": \\\"2026\\\" }\""
  → outer parse → "{ \"date\": \"2026\" }" (str)
  → inner parse → {"date": "2026"} (dict ✓) → peel: args becomes the inner JSON string ✓

• Plain JSON object (normal case): "{\"date\": \"2026\"}"
  → outer parse → {"date": "2026"} (dict, not str) → no peel ✓

• Legitimate string primitive (raw schema, e.g. content="hello"): "\"hello\""
  → outer parse → "hello" (str)
  → inner parse → JSONDecodeError (not valid JSON object) → no peel: args stays "\"hello\"" ✓
  (Without this guard, args would be rewritten to bare hello — invalid JSON — breaking from_json() downstream.)

if isinstance(args, str):
    try:
        parsed = json.loads(args)
        if isinstance(parsed, str):
            try:
                inner = json.loads(parsed)
                if isinstance(inner, dict):
                    args = parsed  # peel one layer of double-encoding
            except (json.JSONDecodeError, TypeError):
                pass  # inner string is a plain value, leave args untouched
    except (json.JSONDecodeError, TypeError):
        pass

Changes

• livekit-plugins/livekit-plugins-aws/livekit/plugins/aws/experimental/realtime/realtime_model.py — unwrap guard in _handle_tool_output_content_event
• livekit-plugins/livekit-plugins-aws/tests/test_nova_sonic_tool_args.py — 5 regression tests

Test plan

• test_doubly_encoded_string_is_unwrapped — Nova Sonic bug case fixed
• test_single_encoded_string_passed_through — normal JSON object args unaffected
• test_invalid_json_string_does_not_crash — invalid JSON left as-is, no crash
• test_string_primitive_schema_not_unwrapped — "hello" stays '"hello"', not rewritten to bare hello
• test_tool_name_and_id_forwarded_correctly — metadata forwarded correctly

[CLAassistant]

All committers have signed the CLA.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.