Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

patch: preserve parallel Chat tool-call identities (#1993)

Ali Khokharf1f798c79054
diff --git a/src/free_claude_code/providers/openai_chat/tool_call_identity.py b/src/free_claude_code/providers/openai_chat/tool_call_identity.py
new file mode 100644
index 00000000..b7a5598d
--- /dev/null
+++ b/src/free_claude_code/providers/openai_chat/tool_call_identity.py
@@ -0,0 +1,74 @@
+"""Resolve provider tool identities within one Chat response attempt."""
+
+from dataclasses import dataclass
+
+from free_claude_code.providers.failure_policy import RetryableToolProtocolError
+
+
+class AmbiguousToolCallIdentityError(RetryableToolProtocolError):
+ """A fragment lacks sufficient identity to assign its content safely."""
+
+
+@dataclass(slots=True)
+class _ToolCallIdentity:
+ index: int | None = None
+ tool_id: str | None = None
+
+
+class ToolCallIdentityResolver:
+ """Keep upstream indexes and IDs separate from locally allocated slots."""
+
+ def __init__(self) -> None:
+ self._calls: list[_ToolCallIdentity] = []
+
+ def allocate(self) -> int:
+ """Reserve a new logical slot, including for already-completed calls."""
+ slot = len(self._calls)
+ self._calls.append(_ToolCallIdentity())
+ return slot
+
+ def resolve(self, raw_index: object, raw_id: object) -> int:
+ index = (
+ raw_index
+ if isinstance(raw_index, int)
+ and not isinstance(raw_index, bool)
+ and raw_index >= 0
+ else None
+ )
+ tool_id = raw_id if isinstance(raw_id, str) and raw_id.strip() else None
+ if index is None and tool_id is None:
+ raise AmbiguousToolCallIdentityError(
+ "Upstream tool-call fragment has neither a usable index nor an ID."
+ )
+
+ matches = [
+ slot
+ for slot, call in enumerate(self._calls)
+ if (index is None or call.index in (None, index))
+ and (tool_id is None or call.tool_id in (None, tool_id))
+ ]
+ # A new identifier starts a call unless a known field links it to one.
+ # Once linked, missing fields on other calls still make it ambiguous.
+ if not any(
+ (index is not None and self._calls[slot].index == index)
+ or (tool_id is not None and self._calls[slot].tool_id == tool_id)
+ for slot in matches
+ ):
+ matches = []
+ if len(matches) > 1:
+ raise AmbiguousToolCallIdentityError(
+ "Upstream tool-call fragment has ambiguous identity."
+ )
+ slot = matches[0] if matches else self.allocate()
+ call = self._calls[slot]
+ if index is not None:
+ call.index = index
+ if tool_id is not None:
+ call.tool_id = tool_id
+ return slot
+
+ def tool_id(self, slot: int) -> str | None:
+ return self._calls[slot].tool_id
+
+ def order_key(self, slot: int) -> tuple[int, int]:
+ return self._calls[slot].index or 0, slot
diff --git a/src/free_claude_code/providers/openai_chat/tool_calls.py b/src/free_claude_code/providers/openai_chat/tool_calls.py
index 6e2476d7..f8fceddd 100644
--- a/src/free_claude_code/providers/openai_chat/tool_calls.py
+++ b/src/free_claude_code/providers/openai_chat/tool_calls.py
@@ -14,13 +14,13 @@ from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.openai_tool_names import OpenAIToolNameCodec
from .stream_output import ChatStreamOutput
+from .tool_call_identity import ToolCallIdentityResolver
RecordToolExtraContent = Callable[[str, dict[str, Any]], None]
@dataclass(slots=True)
class _CollectedToolCall:
- index: int
tool_id: str | None = None
name: str = ""
argument_parts: list[str] = field(default_factory=list)
@@ -35,7 +35,6 @@ class _CompletedOpenAIToolFunction(TypedDict):
class CompletedOpenAIToolCall(TypedDict):
"""Schema-valid OpenAI tool-call payload collected for recovery emission."""
- index: int
id: str | None
function: _CompletedOpenAIToolFunction
extra_content: NotRequired[JsonObject]
@@ -45,6 +44,7 @@ class OpenAIToolCallCollector:
"""Collect and validate one buffered OpenAI tool-call response."""
def __init__(self) -> None:
+ self._identities = ToolCallIdentityResolver()
self._calls: dict[int, _CollectedToolCall] = {}
@property
@@ -53,13 +53,11 @@ class OpenAIToolCallCollector:
def add(self, tool_call: Any) -> None:
"""Add one SDK tool-call delta without emitting downstream state."""
- raw_index = getattr(tool_call, "index", 0)
- index = raw_index if isinstance(raw_index, int) and raw_index >= 0 else 0
- state = self._calls.setdefault(index, _CollectedToolCall(index=index))
-
- tool_id = getattr(tool_call, "id", None)
- if tool_id:
- state.tool_id = str(tool_id)
+ index = self._identities.resolve(
+ getattr(tool_call, "index", None), getattr(tool_call, "id", None)
+ )
+ state = self._calls.setdefault(index, _CollectedToolCall())
+ state.tool_id = self._identities.tool_id(index)
function = getattr(tool_call, "function", None)
incoming_name = getattr(function, "name", None)
@@ -83,7 +81,7 @@ class OpenAIToolCallCollector:
) -> tuple[CompletedOpenAIToolCall, ...] | None:
"""Return complete schema-valid calls, or None when output is incomplete."""
completed: list[CompletedOpenAIToolCall] = []
- for index in sorted(self._calls):
+ for index in sorted(self._calls, key=self._identities.order_key):
state = self._calls[index]
wire_name = state.name.strip()
name = tool_names.decode(wire_name) if tool_names is not None else wire_name
@@ -104,7 +102,6 @@ class OpenAIToolCallCollector:
return None
call: CompletedOpenAIToolCall = {
- "index": index,
"id": state.tool_id,
"function": {
"name": name,
@@ -153,6 +150,7 @@ class OpenAIToolCallAssembler:
) -> None:
self._record_extra_content = record_extra_content
self._reserved_tool_ids = {tool_id for tool_id in reserved_tool_ids if tool_id}
+ self._identities = ToolCallIdentityResolver()
self._candidate_tool_ids: dict[int, str] = {}
self._public_tool_ids: dict[int, str] = {}
@@ -167,10 +165,29 @@ class OpenAIToolCallAssembler:
tool_argument_alias_buffers: dict[int, str] | None = None,
) -> Iterator[str]:
"""Process one tool-call delta and yield client-protocol events."""
- raw_index = tc.get("index", 0)
- tc_index = raw_index if isinstance(raw_index, int) else 0
- if tc_index < 0:
- tc_index = len(output.tool_states)
+ tc_index = self._identities.resolve(tc.get("index"), tc.get("id"))
+ yield from self._process_resolved_tool_call(
+ tc_index,
+ tc,
+ output,
+ tool_names=tool_names,
+ tool_name_buffers=tool_name_buffers,
+ tool_argument_aliases=tool_argument_aliases,
+ tool_argument_alias_buffers=tool_argument_alias_buffers,
+ )
+
+ def _process_resolved_tool_call(
+ self,
+ tc_index: int,
+ tc: Mapping[str, Any],
+ output: ChatStreamOutput,
+ *,
+ tool_names: OpenAIToolNameCodec | None = None,
+ tool_name_buffers: dict[int, str] | None = None,
+ tool_argument_aliases: dict[str, dict[str, str]] | None = None,
+ tool_argument_alias_buffers: dict[int, str] | None = None,
+ ) -> Iterator[str]:
+ """Apply content to a slot already owned by this assembler."""
fn_delta = tc.get("function", {})
incoming_name = fn_delta.get("name")
@@ -253,6 +270,21 @@ class OpenAIToolCallAssembler:
tool_argument_alias_buffers=tool_argument_alias_buffers,
)
+ def process_completed_calls(
+ self,
+ calls: Iterable[CompletedOpenAIToolCall],
+ output: ChatStreamOutput,
+ ) -> Iterator[str]:
+ """Replace abandoned, unstarted tools with collected recovery calls."""
+ self._identities = ToolCallIdentityResolver()
+ self._candidate_tool_ids.clear()
+ self._public_tool_ids.clear()
+ output.tool_states.clear()
+ for call in calls:
+ yield from self._process_resolved_tool_call(
+ self._identities.allocate(), call, output
+ )
+
def _assign_public_tool_id(self, tool_index: int) -> str:
assigned = self._public_tool_ids.get(tool_index)
if assigned is not None:
@@ -282,9 +314,9 @@ class OpenAIToolCallAssembler:
"""Resolve names held only because they also prefix a generated alias."""
for tool_index, name in list(tool_name_buffers.items()):
tool_name_buffers.pop(tool_index, None)
- yield from self.process_tool_call(
+ yield from self._process_resolved_tool_call(
+ tool_index,
{
- "index": tool_index,
"function": {"name": name, "arguments": ""},
},
output,
diff --git a/src/free_claude_code/providers/openai_chat/transport.py b/src/free_claude_code/providers/openai_chat/transport.py
index 2a03abb1..b6c33b39 100644
--- a/src/free_claude_code/providers/openai_chat/transport.py
+++ b/src/free_claude_code/providers/openai_chat/transport.py
@@ -97,6 +97,7 @@ from free_claude_code.providers.request_recovery import (
)
from free_claude_code.providers.stream_recovery import (
RecoveryController,
+ RecoveryDecision,
RecoveryFailureAction,
TruncatedProviderStreamError,
)
@@ -114,6 +115,7 @@ from .stream_output import (
ChatStreamUsage,
ResponsesChatStreamOutput,
)
+from .tool_call_identity import AmbiguousToolCallIdentityError
from .tool_calls import (
CompletedOpenAIToolCall,
OpenAIToolCallAssembler,
@@ -264,10 +266,14 @@ class _OpenAIChatStreamAssembler:
self._raw_stop_seen = True
def recovered_tool_call_events(
- self, tool_call: CompletedOpenAIToolCall
+ self, tool_calls: tuple[CompletedOpenAIToolCall, ...]
) -> Iterator[str]:
- """Emit one buffered recovery call through this attempt's ID scope."""
- yield from self._tool_calls.process_tool_call(tool_call, self._output)
+ """Import a complete recovery batch without inheriting abandoned tools."""
+ if self._output.has_emitted_tool_block():
+ raise RuntimeError("cannot replace started tool calls with recovery output")
+ self._tool_name_buffers.clear()
+ self._tool_argument_alias_buffers.clear()
+ yield from self._tool_calls.process_completed_calls(tool_calls, self._output)
def start_events(self) -> Iterator[str]:
if self._started:
@@ -1218,15 +1224,37 @@ class _OpenAIChatStreamRunner:
else is_retryable_stream_error(error)
)
generated_output = assembler.generated_output
- complete_tool_salvageable = assembler.complete_tool_salvageable
- decision = recovery.advance_failure(
- retryable=retryable,
- stream_opened=scope is not None,
- generated_output=generated_output,
- complete_tool_salvageable=complete_tool_salvageable,
- attempts_remaining=execution.attempts_remaining,
- normal_stop_seen=assembler.normal_stop_seen,
+ identity_failure = isinstance(error, AmbiguousToolCallIdentityError)
+ complete_tool_salvageable = (
+ not identity_failure and assembler.complete_tool_salvageable
)
+ if identity_failure and execution.delivery is None:
+ # Schema-valid arguments cannot prove which call owned a fragment.
+ # Only private output still held here can be discarded and replayed.
+ action = RecoveryFailureAction.FINAL_ERROR
+ if (
+ retryable
+ and not recovery.committed
+ and not assembler.normal_stop_seen
+ and execution.can_attempt
+ ):
+ recovery.discard()
+ action = RecoveryFailureAction.EARLY_RETRY
+ decision = RecoveryDecision(
+ action=action,
+ retryable=retryable,
+ committed=recovery.committed,
+ has_buffered=recovery.has_buffered,
+ )
+ else:
+ decision = recovery.advance_failure(
+ retryable=retryable,
+ stream_opened=scope is not None,
+ generated_output=generated_output,
+ complete_tool_salvageable=complete_tool_salvageable,
+ attempts_remaining=execution.attempts_remaining,
+ normal_stop_seen=assembler.normal_stop_seen,
+ )
tag = self._transport._provider_name
if decision.action == RecoveryFailureAction.EARLY_RETRY:
trace_event(
@@ -1359,6 +1387,7 @@ class _OpenAIChatStreamRunner:
last_error: Exception | None = None
while execution.can_attempt:
scope: ProviderAttemptScope | None = None
+ terminal_seen = False
try:
(
stream,
@@ -1382,7 +1411,6 @@ class _OpenAIChatStreamRunner:
text_parts: list[str] = []
thinking_parts: list[str] = []
tool_calls = OpenAIToolCallCollector()
- terminal_seen = False
async for chunk in stream:
if not scope.attempt.accepted:
await scope.attempt.accept()
@@ -1439,7 +1467,14 @@ class _OpenAIChatStreamRunner:
),
)
retryable = failure.retryable
- if not retryable or not execution.can_attempt:
+ if (
+ not retryable
+ or not execution.can_attempt
+ or (
+ isinstance(error, AmbiguousToolCallIdentityError)
+ and terminal_seen
+ )
+ ):
raise
trace_event(
stage="provider",
@@ -1542,8 +1577,7 @@ class _OpenAIChatStreamRunner:
events.append(output.emit_text_delta(text_suffix))
if recovered.tool_calls:
events.extend(output.close_content_blocks())
- for tool_call in recovered.tool_calls:
- events.extend(assembler.recovered_tool_call_events(tool_call))
+ events.extend(assembler.recovered_tool_call_events(recovered.tool_calls))
if not events:
return None
events.extend(
diff --git a/tests/api/test_chat_tool_identity_api.py b/tests/api/test_chat_tool_identity_api.py
new file mode 100644
index 00000000..1d9dd5d3
--- /dev/null
+++ b/tests/api/test_chat_tool_identity_api.py
@@ -0,0 +1,526 @@
+"""Public API routes preserve parallel Chat calls with imperfect indexes."""
+
+import json
+
+import httpx2
+import pytest
+from fastapi.testclient import TestClient
+from openai import AsyncOpenAI
+
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.providers.gemini import GeminiProvider
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.support import create_test_app
+from tests.api.test_hidden_stream_retries import delivered
+from tests.api.test_tool_call_buffer_transports import _tools
+from tests.providers.support import immediate_admission, make_provider_config
+from tests.providers.test_chat_tool_identity import call
+from tests.providers.test_history_transports import _harness, _saved_reply
+from tests.providers.test_native_tool_arguments import tool_events
+
+
+def chat_chunk(delta, finish=None):
+ return {
+ "id": "chat_identity",
+ "object": "chat.completion.chunk",
+ "created": 0,
+ "model": "test-model",
+ "choices": [{"index": 0, "delta": delta, "finish_reason": finish}],
+ }
+
+
+def gemini_api_response(monkeypatch, events, wire, streaming, *, max_attempts=2):
+ sent = []
+ upstream = (
+ "".join(f"data: {json.dumps(event)}\n\n" for event in events)
+ + "data: [DONE]\n\n"
+ )
+
+ def reply(request):
+ sent.append(json.loads(request.content))
+ return httpx2.Response(
+ 200, headers={"content-type": "text/event-stream"}, content=upstream
+ )
+
+ sdk = AsyncOpenAI(
+ api_key="fixture",
+ base_url="https://fixture.invalid/v1",
+ max_retries=0,
+ http_client=httpx2.AsyncClient(transport=httpx2.MockTransport(reply)),
+ )
+ monkeypatch.setattr(
+ "free_claude_code.providers.openai_chat.client.AsyncOpenAI", lambda **_: sdk
+ )
+ provider = GeminiProvider(
+ make_provider_config(api_key="fixture", base_url="https://fixture.invalid/v1"),
+ admission=immediate_admission(max_attempts=max_attempts),
+ )
+ app = create_test_app(
+ Settings(MODEL="gemini/test-model", ENABLE_WEB_SERVER_TOOLS=False),
+ providers={"gemini": provider},
+ )
+ schema = {"type": "object", "properties": {"path": {"type": "string"}}}
+ if wire == "messages":
+ body = {
+ "model": "gemini/test-model",
+ "max_tokens": 100,
+ "stream": streaming,
+ "messages": [{"role": "user", "content": "read both"}],
+ "tools": [{"name": "read", "input_schema": schema}],
+ }
+ else:
+ body = {
+ "model": "gemini/test-model",
+ "stream": True,
+ "input": "read both",
+ "tools": [{"type": "function", "name": "read", "parameters": schema}],
+ }
+ with TestClient(app) as client:
+ response = client.post(f"/v1/{wire}", json=body)
+ return response, sent
+
+
+ "deltas,expected_ids",
+ [
+ (
+ [
+ [
+ call(first, "call_a", '{"path":"a"}'),
+ call(second, "call_b", '{"path":"b"}'),
+ ]
+ ],
+ ("call_a", "call_b"),
+ )
+ for first, second in [(0, 1), (0, 0), (None, None), ("missing", "missing")]
+ ]
+ + [
+ (
+ [
+ [call(None, "call_a", '{"path":"a"}')],
+ [call(1, None, '{"path":"b"}')],
+ [call(1, "call_b", "", name=None)],
+ ],
+ ("call_a", None),
+ ),
+ (
+ [
+ [call(0, None, '{"path":"a"}')],
+ [call(None, "call_b", '{"path":"b"}')],
+ [call(0, "call_a", "", name=None)],
+ ],
+ (None, "call_b"),
+ ),
+ (
+ [
+ [
+ call(0, "call_a", '{"path":'),
+ call(0, None, '"a"}', name=None),
+ call(1, "call_b", '{"path":"b"}'),
+ ]
+ ],
+ ("call_a", "call_b"),
+ ),
+ ],
+ ids=[
+ "distinct",
+ "reused",
+ "null",
+ "missing",
+ "late_id",
+ "late_index",
+ "same_chunk",
+ ],
+)
+ "wire,streaming", [("messages", True), ("messages", False), ("responses", True)]
+)
+def test_gemini_parallel_calls_reach_public_api(
+ monkeypatch, deltas, expected_ids, wire, streaming
+):
+ events = [chat_chunk({"tool_calls": calls}) for calls in deltas]
+ events.append(chat_chunk({}, "tool_calls"))
+ response, sent = gemini_api_response(monkeypatch, events, wire, streaming)
+ assert response.status_code == 200, response.text
+ assert len(sent) == 1
+
+ if not streaming:
+ values = [
+ (item["id"], item["name"], item["input"])
+ for item in response.json()["content"]
+ if item["type"] == "tool_use"
+ ]
+ elif wire == "messages":
+ calls = {}
+ events = parse_sse_text(response.text)
+ assert events[-1].event == "message_stop"
+ for event in events:
+ data = event.data
+ block = data.get("content_block", {})
+ if block.get("type") == "tool_use":
+ calls[data["index"]] = {
+ "id": block["id"],
+ "name": block["name"],
+ "arguments": "",
+ }
+ if data.get("delta", {}).get("type") == "input_json_delta":
+ calls[data["index"]]["arguments"] += data["delta"]["partial_json"]
+ values = [
+ (item["id"], item["name"], json.loads(item["arguments"]))
+ for item in calls.values()
+ ]
+ else:
+ events = parse_sse_text(response.text)
+ assert events[-1].event == "response.completed"
+ values = [
+ (item["call_id"], item["name"], json.loads(item["arguments"]))
+ for item in events[-1].data["response"]["output"]
+ if item["type"] == "function_call"
+ ]
+ assert [(name, arguments) for _, name, arguments in values] == [
+ ("read", {"path": "a"}),
+ ("read", {"path": "b"}),
+ ]
+ assert len({tool_id for tool_id, _, _ in values}) == 2
+ for (tool_id, _, _), expected_id in zip(values, expected_ids, strict=True):
+ if expected_id is None:
+ assert tool_id.startswith("tool_")
+ else:
+ assert tool_id == expected_id
+
+
[email protected]("anonymous", [True, False])
+ "wire,streaming", [("messages", True), ("messages", False), ("responses", True)]
+)
+def test_gemini_unresolvable_calls_cannot_complete(
+ monkeypatch, anonymous, wire, streaming
+):
+ if anonymous:
+ events = [
+ chat_chunk(
+ {
+ "tool_calls": [
+ call(None, None, '{"path":"a"}'),
+ call(None, None, '{"path":"b"}'),
+ ]
+ }
+ )
+ ]
+ else:
+ # Either call could own the index-only fragment. Both assignments
+ # would produce valid JSON, so argument validation cannot decide.
+ events = [
+ chat_chunk(
+ {
+ "tool_calls": [
+ call(0, "call_a", '{"path":"a'),
+ call(None, "call_b", '{"path":"b'),
+ ]
+ }
+ ),
+ chat_chunk({"tool_calls": [call(0, None, "_part", name=None)]}),
+ chat_chunk({"tool_calls": [call(0, "call_b", '"}', name=None)]}),
+ chat_chunk({"tool_calls": [call(0, "call_a", '"}', name=None)]}),
+ ]
+ events.append(chat_chunk({}, "tool_calls"))
+ response, sent = gemini_api_response(
+ monkeypatch, events, wire, streaming, max_attempts=1
+ )
+ assert len(sent) == 1
+ # The public tool buffer has not committed a response, so failure can
+ # still be reported as an HTTP error for streaming requests too.
+ assert response.status_code == 502
+ assert isinstance(response.json().get("error"), dict)
+
+
+def completed_arguments(events, wire):
+ if wire == "messages":
+ return "".join(
+ event.data["delta"]["partial_json"]
+ for event in events
+ if event.data.get("delta", {}).get("type") == "input_json_delta"
+ )
+ return "".join(
+ event.data["item"]["arguments"]
+ for event in events
+ if event.event == "response.output_item.done"
+ and event.data["item"]["type"] == "function_call"
+ )
+
+
+def ambiguous_events(stop, *, incomplete=False, fragment_index=0):
+ events = [
+ chat_chunk(
+ {
+ "tool_calls": [
+ call(
+ 0,
+ "call_abandoned_a",
+ '{"path":' if incomplete else '{"path":"a"}',
+ ),
+ call(
+ 0,
+ "call_abandoned_b",
+ '{"path":' if incomplete else '{"path":"b"}',
+ ),
+ ]
+ }
+ )
+ ]
+ if stop == "before":
+ events.append(chat_chunk({}, "tool_calls"))
+ events.append(
+ chat_chunk(
+ {"tool_calls": [call(fragment_index, None, "uncertain", name=None)]},
+ "tool_calls" if stop == "same" else None,
+ )
+ )
+ return events
+
+
[email protected]("wire", ["messages", "responses"])
[email protected]("prefix", [None, "content", "reasoning_content"])
[email protected]("stop", [None, "same", "before"])
[email protected]("max_attempts", [1, 2])
[email protected]("fragment_index", [0, None])
+async def test_public_identity_failure_respects_delivery_stop_and_budget(
+ monkeypatch, wire, prefix, stop, max_attempts, fragment_index
+):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+ first = ambiguous_events(stop, fragment_index=fragment_index)
+ if prefix:
+ first.insert(0, chat_chunk({prefix: "already visible"}))
+ async with _harness(
+ "chat",
+ lambda bodies: (
+ 200,
+ first if len(bodies) == 1 else tool_events("chat", '{"path":"winning"}'),
+ ),
+ max_attempts=max_attempts,
+ ) as (send, bodies, _):
+ result = await delivered(
+ send(wire, [{"role": "user", "content": "read"}], tools=_tools(wire)), wire
+ )
+
+ # OpenRouter's Messages thinking includes a Chat replay signature, which
+ # the existing public continuation policy treats as opaque.
+ opaque = wire == "messages" and prefix == "reasoning_content"
+ retry = stop is None and max_attempts > 1 and not opaque
+ assert len(bodies) == (2 if retry else 1)
+ assert "call_abandoned" not in result
+ events = parse_sse_text(result)
+ if prefix:
+ assert "already visible" in result
+ if retry:
+ assert completed_arguments(events, wire) == '{"path":"winning"}'
+ assert events[-1].event == (
+ "message_stop" if wire == "messages" else "response.completed"
+ )
+ assert bodies[1]["tools"] == bodies[0]["tools"]
+ if prefix:
+ assert "already visible" in str(bodies[1])
+ else:
+ assert bodies[0] == bodies[1]
+ else:
+ assert events[-1].event == (
+ "error" if wire == "messages" else "response.failed"
+ )
+ assert "winning" not in result
+ assert not any(
+ event.event
+ in {"response.function_call_arguments.done", "response.output_item.done"}
+ and (
+ event.event != "response.output_item.done"
+ or event.data["item"]["type"] == "function_call"
+ )
+ for event in events
+ )
+
+
[email protected]("wire", ["messages", "responses"])
[email protected]("incomplete", [False, True])
[email protected]("fragment_index", [0, None])
+ "committed,stop,max_attempts",
+ [
+ (False, None, 2),
+ (False, None, 1),
+ (True, None, 2),
+ (False, "same", 2),
+ (False, "before", 2),
+ (True, "same", 2),
+ ],
+)
+async def test_private_identity_failure_never_salvages_or_repairs(
+ monkeypatch, wire, incomplete, committed, stop, max_attempts, fragment_index
+):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(
+ holdback_seconds=60, max_bytes=1 if committed else 1_000_000
+ ),
+ )
+ first = ambiguous_events(stop, incomplete=incomplete, fragment_index=fragment_index)
+ emitted = []
+ failure = None
+ async with _harness(
+ "chat",
+ lambda bodies: (
+ 200,
+ first if len(bodies) == 1 else tool_events("chat", '{"path":"winning"}'),
+ ),
+ max_attempts=max_attempts,
+ ) as (send, bodies, _):
+ try:
+ async for event in send(
+ wire, [{"role": "user", "content": "read"}], tools=_tools(wire)
+ ):
+ # Retain the prefix even when iteration raises before completion.
+ emitted.extend((event,))
+ except ExecutionFailure as error:
+ failure = error
+
+ retry = not committed and stop is None and max_attempts > 1
+ assert len(bodies) == (2 if retry else 1)
+ result = "".join(emitted)
+ events = parse_sse_text(result)
+ if retry:
+ assert failure is None
+ assert bodies[0] == bodies[1]
+ assert "call_abandoned" not in result
+ assert completed_arguments(events, wire) == '{"path":"winning"}'
+ assert events[-1].event == (
+ "message_stop" if wire == "messages" else "response.completed"
+ )
+ else:
+ assert failure is not None or any(
+ event.event == "response.failed" for event in events
+ )
+ assert not any(
+ event.event
+ in {
+ "message_stop",
+ "response.completed",
+ "response.function_call_arguments.done",
+ }
+ for event in events
+ )
+ started_tools = {
+ event.data["index"]
+ for event in events
+ if event.event == "content_block_start"
+ and event.data["content_block"]["type"] == "tool_use"
+ }
+ assert not any(
+ event.event == "content_block_stop" and event.data["index"] in started_tools
+ for event in events
+ )
+
+
[email protected]("wire", ["messages", "responses"])
+ "indexes,ids",
+ [
+ ((0, 0), ("call_a", "call_b")),
+ ((None, None), ("call_a", "call_b")),
+ ((0, 1), ("reused", "reused")),
+ ],
+)
+async def test_gemini_metadata_replays_under_each_public_id(wire, indexes, ids):
+ first = [
+ chat_chunk(
+ {
+ "tool_calls": [
+ call(
+ indexes[0],
+ ids[0],
+ '{"path":"a"}',
+ metadata={"google": {"thought_signature": "sig-a"}},
+ ),
+ call(
+ indexes[1],
+ ids[1],
+ '{"path":"b"}',
+ metadata={"google": {"thought_signature": "sig-b"}},
+ ),
+ ]
+ }
+ ),
+ chat_chunk({}, "tool_calls"),
+ ]
+
+ def gemini():
+ return GeminiProvider(
+ make_provider_config("fixture", "https://provider.invalid/v1"),
+ admission=immediate_admission(max_attempts=2),
+ )
+
+ async with _harness(
+ "chat",
+ lambda bodies: (
+ 200,
+ first if len(bodies) == 1 else [chat_chunk({"content": "done"}, "stop")],
+ ),
+ chat_provider_factory=gemini,
+ ) as (send, bodies, _):
+ saved = await _saved_reply(
+ send(wire, [{"role": "user", "content": "read both"}], tools=_tools(wire)),
+ wire,
+ )
+ if wire == "messages":
+ calls = [item for item in saved[0]["content"] if item["type"] == "tool_use"]
+ public_ids = [item["id"] for item in calls]
+ followup = [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": item["id"],
+ "name": item["name"],
+ "input": item["input"],
+ }
+ for item in calls
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {"type": "tool_result", "tool_use_id": tool_id, "content": "ok"}
+ for tool_id in public_ids
+ ],
+ },
+ ]
+ else:
+ calls = [item for item in saved if item["type"] == "function_call"]
+ public_ids = [item["call_id"] for item in calls]
+ followup = [
+ {
+ "type": "function_call",
+ "call_id": item["call_id"],
+ "name": item["name"],
+ "arguments": item["arguments"],
+ }
+ for item in calls
+ ] + [
+ {"type": "function_call_output", "call_id": tool_id, "output": "ok"}
+ for tool_id in public_ids
+ ]
+ assert len(set(public_ids)) == 2
+ await _saved_reply(send(wire, followup, tools=_tools(wire)), wire)
+ replayed = next(
+ row["tool_calls"] for row in bodies[1]["messages"] if row.get("tool_calls")
+ )
+ assert [(item["id"], item["extra_content"]) for item in replayed] == [
+ (public_ids[0], {"google": {"thought_signature": "sig-a"}}),
+ (public_ids[1], {"google": {"thought_signature": "sig-b"}}),
+ ]
diff --git a/tests/providers/test_chat_tool_identity.py b/tests/providers/test_chat_tool_identity.py
new file mode 100644
index 00000000..bd2e0cb3
--- /dev/null
+++ b/tests/providers/test_chat_tool_identity.py
@@ -0,0 +1,546 @@
+"""Chat tool identity survives missing or reused upstream indexes."""
+
+import json
+from copy import deepcopy
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.anthropic.streaming import ToolSchema
+from free_claude_code.core.openai_tool_names import OpenAIToolNameCodec
+from free_claude_code.providers.admission import ProviderOperationKind
+from free_claude_code.providers.failure_policy import RetryableToolProtocolError
+from free_claude_code.providers.openai_chat.tool_calls import (
+ OpenAIToolCallAssembler,
+ OpenAIToolCallCollector,
+)
+from free_claude_code.providers.request_recovery import RequestRecovery
+from tests.providers.test_streaming_errors import (
+ ClosableAsyncStreamMock,
+ _make_anthropic_output,
+ _make_chunk,
+ _make_provider,
+ _make_request,
+ _make_stream_runner,
+ _recovery_output,
+)
+
+SCHEMAS = {"read": ToolSchema(name="read", input_schema={"type": "object"})}
+
+
+def call(index=0, tool_id="call_a", arguments="{}", *, name="read", metadata=None):
+ delta = {
+ "id": tool_id,
+ "function": {"name": name, "arguments": arguments},
+ }
+ if index != "missing":
+ delta["index"] = index
+ if metadata is not None:
+ delta["extra_content"] = metadata
+ return delta
+
+
+def sdk_call(delta):
+ return SimpleNamespace(
+ **{**delta, "function": SimpleNamespace(**delta["function"])}
+ )
+
+
[email protected](params=["stream", "collector"])
+def call_consumer(request):
+ output = _make_anthropic_output()
+ assembler = OpenAIToolCallAssembler(reserved_tool_ids=())
+ collector = OpenAIToolCallCollector()
+
+ def add(delta):
+ if request.param == "stream":
+ list(assembler.process_tool_call(delta, output))
+ else:
+ collector.add(sdk_call(delta))
+
+ def completed():
+ if request.param == "stream":
+ return [
+ {
+ "id": state.tool_id,
+ "name": state.name,
+ "arguments": state.content,
+ "metadata": state.extra_content,
+ }
+ for state in output.tool_states.values()
+ ]
+ calls = collector.completed_calls(SCHEMAS)
+ assert calls is not None
+ return [
+ {
+ "id": item["id"],
+ "name": item["function"]["name"],
+ "arguments": item["function"]["arguments"],
+ "metadata": item.get("extra_content"),
+ }
+ for item in calls
+ ]
+
+ return add, completed
+
+
+ "indexes", [(0, 1), (0, 0), (None, None), ("missing", "missing")]
+)
[email protected]("fragmented", [False, True])
+def test_parallel_calls_keep_arguments_and_metadata(call_consumer, indexes, fragmented):
+ add, completed = call_consumer
+ arguments = ['{"path":"a"}', '{"path":"b"}']
+ for index, tool_id, argument in zip(
+ indexes, ("call_a", "call_b"), arguments, strict=True
+ ):
+ add(
+ call(
+ index,
+ tool_id,
+ argument[:8] if fragmented else argument,
+ metadata={"google": {"thought_signature": tool_id}},
+ )
+ )
+ if fragmented:
+ for position in (1, 0):
+ add(
+ call(
+ indexes[position],
+ ("call_a", "call_b")[position],
+ arguments[position][8:],
+ name=None,
+ )
+ )
+
+ assert completed() == [
+ {
+ "id": "call_a",
+ "name": "read",
+ "arguments": '{"path":"a"}',
+ "metadata": {"google": {"thought_signature": "call_a"}},
+ },
+ {
+ "id": "call_b",
+ "name": "read",
+ "arguments": '{"path":"b"}',
+ "metadata": {"google": {"thought_signature": "call_b"}},
+ },
+ ]
+
+
+def test_allocated_slots_do_not_alias_later_raw_indexes(call_consumer):
+ add, completed = call_consumer
+ for index, tool_id, arguments in (
+ (0, "call_a", '{"path":"a"}'),
+ (0, "call_b", '{"path":"b"}'),
+ (1, "call_c", '{"path":"c"}'),
+ ):
+ add(call(index, tool_id, arguments))
+ assert [item["arguments"] for item in completed()] == [
+ '{"path":"a"}',
+ '{"path":"b"}',
+ '{"path":"c"}',
+ ]
+
+
[email protected]("index", [None, "missing", -1, "invalid"])
+def test_unusable_index_keeps_fragments_of_one_id_together(call_consumer, index):
+ add, completed = call_consumer
+ add(call(index, "call_a", '{"path":', name=None))
+ add(call(index, "call_a", '"a"}'))
+ assert [item["arguments"] for item in completed()] == ['{"path":"a"}']
+
+
+ "first,second",
+ [
+ (call(0, None, '{"path":', name=None), call(0, "call_a", '"a"}')),
+ (call(None, "call_a", '{"path":', name=None), call(4, "call_a", '"a"}')),
+ (call(0, "call_a", '{"path":'), call(0, None, '"a"}', name=None)),
+ ],
+)
+def test_partial_identity_can_learn_missing_fields(call_consumer, first, second):
+ add, completed = call_consumer
+ add(first)
+ add(second)
+ assert [item["arguments"] for item in completed()] == ['{"path":"a"}']
+
+
+ "identities",
+ [
+ [(None, "call_a"), (1, None), (1, "call_b")],
+ [(0, None), (None, "call_b"), (0, "call_a")],
+ ],
+)
+def test_disjoint_partial_identities_keep_content_separate(call_consumer, identities):
+ add, completed = call_consumer
+ for (index, tool_id), path in zip(identities[:2], ("a", "b"), strict=True):
+ add(
+ call(
+ index,
+ tool_id,
+ '{"path":"' + path + '"}',
+ metadata={"google": {"thought_signature": path}},
+ )
+ )
+ index, tool_id = identities[2]
+ add(call(index, tool_id, "", name=None))
+ assert [(item["arguments"], item["metadata"]) for item in completed()] == [
+ ('{"path":"a"}', {"google": {"thought_signature": "a"}}),
+ ('{"path":"b"}', {"google": {"thought_signature": "b"}}),
+ ]
+
+
+def test_new_index_does_not_attach_to_unindexed_calls(call_consumer):
+ add, completed = call_consumer
+ add(call(None, "call_a", '{"path":"a"}'))
+ add(call(None, "call_b", '{"path":"b"}'))
+ add(call(3, None, '{"path":"c"}'))
+ assert [item["arguments"] for item in completed()] == [
+ '{"path":"a"}',
+ '{"path":"b"}',
+ '{"path":"c"}',
+ ]
+
+
+ "index,tool_id",
+ [(None, None), ("missing", None), (-1, ""), ("invalid", " "), (False, None)],
+)
[email protected]("existing", [False, True])
+def test_unidentified_fragment_is_rejected_before_content_changes(
+ call_consumer, index, tool_id, existing
+):
+ add, completed = call_consumer
+ if existing:
+ add(call(0, "call_a", '{"path":"a"}', metadata={"original": True}))
+ before = deepcopy(completed())
+ with pytest.raises(RetryableToolProtocolError):
+ add(call(index, tool_id, '{"path":"b"}', metadata={"wrong": True}))
+ assert completed() == before
+
+
+ "initial,fragment",
+ [
+ ([call(0, "call_a"), call(0, "call_b")], call(0, None, "bad")),
+ ([call(0, "same"), call(1, "same")], call(None, "same", "bad")),
+ ([call(0, None), call(1, None)], call(None, None, "bad")),
+ ([call(0, "call_a"), call(None, "call_b")], call(0, None, "bad")),
+ ([call(0, "call_a"), call(1, None)], call(None, "call_a", "bad")),
+ ([call(0, None), call(None, "call_a")], call(0, "call_a", "bad")),
+ ],
+)
+def test_ambiguous_fragment_is_rejected_before_content_changes(
+ call_consumer, initial, fragment
+):
+ add, completed = call_consumer
+ for delta in initial:
+ add(delta)
+ before = deepcopy(completed())
+ with pytest.raises(RetryableToolProtocolError):
+ add(fragment)
+ assert completed() == before
+
+
+def test_collector_preserves_sparse_numeric_order():
+ collector = OpenAIToolCallCollector()
+ collector.add(sdk_call(call(8, "call_a", '{"path":"a"}')))
+ collector.add(sdk_call(call(2, "call_b", '{"path":"b"}')))
+ result = collector.completed_calls(SCHEMAS)
+ assert result is not None
+ assert [item["id"] for item in result] == ["call_b", "call_a"]
+
+
+def test_name_flush_uses_logical_slots_for_repeated_index():
+ request = _make_request(
+ tools=[
+ {"name": "tool", "input_schema": {"type": "object"}},
+ {"name": "tool." + "x" * 70, "input_schema": {"type": "object"}},
+ ]
+ )
+ codec = OpenAIToolNameCodec.from_request(request)
+ output = _make_anthropic_output()
+ assembler = OpenAIToolCallAssembler(reserved_tool_ids=())
+ names = {}
+ for tool_id, argument in (("call_a", '{"path":"a"}'), ("call_b", '{"path":"b"}')):
+ assert (
+ list(
+ assembler.process_tool_call(
+ call(0, tool_id, argument, name="tool"),
+ output,
+ tool_names=codec,
+ tool_name_buffers=names,
+ )
+ )
+ == []
+ )
+ list(
+ assembler.flush_tool_name_buffers(
+ output,
+ tool_names=codec,
+ tool_name_buffers=names,
+ tool_argument_aliases={},
+ tool_argument_alias_buffers={},
+ )
+ )
+ assert [
+ (state.tool_id, state.name, state.content)
+ for state in output.tool_states.values()
+ ] == [
+ ("call_a", "tool", '{"path":"a"}'),
+ ("call_b", "tool", '{"path":"b"}'),
+ ]
+
+
[email protected]("recovered_ids", [(None, None), ("same", "same")])
+async def test_recovery_import_discards_unstarted_call_state(recovered_ids):
+ provider = _make_provider()
+ runner = _make_stream_runner(
+ provider,
+ request=_make_request(
+ tools=[
+ {"name": name, "input_schema": {"type": "object"}}
+ for name in ("read", "tool", "tool." + "x" * 70)
+ ]
+ ),
+ )
+ assembler = runner._new_stream_assembler(output_reasoning=True)
+ list(assembler.start_events())
+ list(
+ assembler.feed(
+ _make_chunk(
+ content="visible",
+ tool_calls=[
+ sdk_call(
+ call(
+ 0,
+ "abandoned",
+ '{"old":',
+ name="tool",
+ metadata={"old": True},
+ )
+ )
+ ],
+ )
+ )
+ )
+ with patch.object(
+ runner,
+ "_collect_recovery_output",
+ new_callable=AsyncMock,
+ return_value=_recovery_output(
+ text="visible",
+ tool_calls=(
+ {
+ "id": recovered_ids[0],
+ "function": {"name": "read", "arguments": "{}"},
+ },
+ {
+ "id": recovered_ids[1],
+ "function": {"name": "read", "arguments": '{"path":"b"}'},
+ "extra_content": {"new": True},
+ },
+ ),
+ ),
+ ):
+ result = await runner._recovery_events(
+ body=runner._body,
+ assembler=assembler,
+ error=TimeoutError("cutoff"),
+ tool_argument_alias_buffers=assembler.tool_argument_alias_buffers,
+ output_reasoning=True,
+ request_recovery=RequestRecovery(provider._admission.start_execution()),
+ )
+ assert result is not None
+ events = parse_sse_text("".join(result))
+ starts = [
+ event.data["content_block"]
+ for event in events
+ if event.event == "content_block_start"
+ ]
+ assert len(starts) == 2
+ assert len({start["id"] for start in starts}) == 2
+ assert "abandoned" not in {start["id"] for start in starts}
+ assert "extra_content" not in starts[0]
+ assert starts[1]["extra_content"] == {"new": True}
+ assert [state.content for state in assembler.output.tool_states.values()] == [
+ "{}",
+ '{"path":"b"}',
+ ]
+ assert assembler.output.accumulated_text == "visible"
+ assert assembler._tool_name_buffers == {}
+ await provider.cleanup()
+
+
[email protected]("stop", [None, "same", "before"])
[email protected]("fragment_index", [0, None])
+async def test_collector_identity_failure_respects_stop_and_closes_attempts(
+ stop, fragment_index
+):
+ provider = _make_provider()
+ runner = _make_stream_runner(
+ provider,
+ request=_make_request(
+ tools=[{"name": "read", "input_schema": {"type": "object"}}]
+ ),
+ )
+ chunks = [
+ _make_chunk(
+ tool_calls=[sdk_call(call(0, "call_a")), sdk_call(call(0, "call_b"))]
+ )
+ ]
+ if stop == "before":
+ chunks.append(_make_chunk(finish_reason="tool_calls"))
+ chunks.append(
+ _make_chunk(
+ tool_calls=[sdk_call(call(fragment_index, None, "uncertain", name=None))],
+ finish_reason="tool_calls" if stop == "same" else None,
+ )
+ )
+ first = ClosableAsyncStreamMock(chunks)
+ winner = ClosableAsyncStreamMock(
+ [
+ _make_chunk(tool_calls=[sdk_call(call(0, "winner", '{"path":"winning"}'))]),
+ _make_chunk(finish_reason="tool_calls"),
+ ]
+ )
+ streams = iter((first, winner))
+
+ async def create_stream(**kwargs):
+ stream = next(streams)
+ if stream is winner:
+ assert first.close_calls == 1
+ return stream
+
+ execution = provider._admission.start_execution()
+ try:
+ with patch.object(
+ provider._client.chat.completions, "create", side_effect=create_stream
+ ):
+ if stop:
+ with pytest.raises(RetryableToolProtocolError):
+ await runner._collect_recovery_output(
+ runner._body,
+ include_reasoning=True,
+ request_recovery=RequestRecovery(execution),
+ operation_kind=ProviderOperationKind.CONTINUATION,
+ )
+ else:
+ result = await runner._collect_recovery_output(
+ runner._body,
+ include_reasoning=True,
+ request_recovery=RequestRecovery(execution),
+ operation_kind=ProviderOperationKind.CONTINUATION,
+ )
+ assert [item["id"] for item in result.tool_calls] == ["winner"]
+ assert (
+ result.tool_calls[0]["function"]["arguments"]
+ == '{"path":"winning"}'
+ )
+ assert execution.attempts_started == (1 if stop else 2)
+ assert first.close_calls == 1
+ assert winner.close_calls == (0 if stop else 1)
+ finally:
+ await runner._request_client.aclose()
+ await provider.cleanup()
+
+
[email protected]("index", [0, None])
+def test_colliding_calls_keep_name_and_argument_alias_buffers_separate(index):
+ original = "tool." + "x" * 70
+ request = _make_request(
+ tools=[
+ {"name": original, "input_schema": {"type": "object"}},
+ {"name": "tool", "input_schema": {"type": "object"}},
+ ]
+ )
+ codec = OpenAIToolNameCodec.from_request(request)
+ assembler = OpenAIToolCallAssembler(reserved_tool_ids=())
+ output = _make_anthropic_output()
+ names = {}
+ arguments = {}
+ aliases = {name: {"_fcc_arg_type": "type"} for name in (original, "tool")}
+ for delta in (
+ call(index, "call_a", '{"_fcc_arg_type":"a', name=codec.encode(original)),
+ call(index, "call_b", '{"_fcc_arg_type":"b', name="tool"),
+ call(index, "call_b", '"}', name=None),
+ call(index, "call_a", '"}', name=None),
+ ):
+ list(
+ assembler.process_tool_call(
+ delta,
+ output,
+ tool_names=codec,
+ tool_name_buffers=names,
+ tool_argument_aliases=aliases,
+ tool_argument_alias_buffers=arguments,
+ )
+ )
+ list(
+ assembler.flush_tool_name_buffers(
+ output,
+ tool_names=codec,
+ tool_name_buffers=names,
+ tool_argument_aliases=aliases,
+ tool_argument_alias_buffers=arguments,
+ )
+ )
+ assert [
+ (state.tool_id, state.name, json.loads(state.content))
+ for state in output.tool_states.values()
+ ] == [("call_a", original, {"type": "a"}), ("call_b", "tool", {"type": "b"})]
+
+
+def test_name_prefix_without_output_state_reserves_its_own_slot():
+ request = _make_request(
+ tools=[
+ {"name": "tool", "input_schema": {"type": "object"}},
+ {"name": "tool." + "x" * 70, "input_schema": {"type": "object"}},
+ ]
+ )
+ codec = OpenAIToolNameCodec.from_request(request)
+ assembler = OpenAIToolCallAssembler(reserved_tool_ids=())
+ output = _make_anthropic_output()
+ names = {}
+ for delta in (
+ call(8, None, "", name="tool"),
+ call(2, "call_b", '{"path":"b"}', name="tool"),
+ call(8, "call_a", '{"path":"a"}', name=None),
+ ):
+ assert (
+ list(
+ assembler.process_tool_call(
+ delta,
+ output,
+ tool_names=codec,
+ tool_name_buffers=names,
+ )
+ )
+ == []
+ )
+ events = list(
+ assembler.flush_tool_name_buffers(
+ output,
+ tool_names=codec,
+ tool_name_buffers=names,
+ tool_argument_aliases={},
+ tool_argument_alias_buffers={},
+ )
+ )
+ starts = [
+ event.data["content_block"]["id"]
+ for event in parse_sse_text("".join(events))
+ if event.event == "content_block_start"
+ ]
+ assert starts == ["call_a", "call_b"]
+ assert {state.tool_id: state.content for state in output.tool_states.values()} == {
+ "call_a": '{"path":"a"}',
+ "call_b": '{"path":"b"}',
+ }