FreeCADWasmDev/docs/current/MODEL_TRANSPORT_RECOVERY.md

Model Transport Recovery

Observed Failure

The direct Codex connection repeatedly produced no completed turn. In a controlled /v1/responses CLI probe, pwd completed at 91.202 seconds but the turn still had not completed at the 120-second limit.

Tracing the HTTP boundary showed stalls before response headers. The gateway does accept Codex's additional_tools and tool-result items: forwarding those unchanged over HTTP/1.1 completed both request stages. No tool schema conversion was required. These observations do not identify the gateway's internal defect.

Project Fix

• tools/codex_http_transport.py provides a loopback-only HTTP/1.1 bridge.
• docs/current/scheduler-transport.json selects https://api.weapi.pw/v1.
• Normal, resumed and periodic-optimization turns all use the same bridge.
• The model remains the existing configured model; global configuration and credentials are unchanged. The bridge forwards authentication in memory.
• The request body, tool definitions, call IDs and tool outputs are unchanged.
• A 60-second request budget and at most one pre-header retry allow transient gateway stalls to recover without abandoning the model session. The scheduler covers this with a 130.5-second minimum response/idle budget.
• No bridge retry occurs after response headers. Authentication errors, rate limits and Retry-After responses are returned to the client. Redirects are not followed. No success or completed event is synthesized.
• The bridge starts and stops with the scheduler and is recreated after a watchdog restart. Configuration can be disabled with enabled=false.

Measured Recovery

The final production-transport probe recorded a successful command at 7.439 seconds and turn.completed at 16.858 seconds, then exited normally. Evidence: transport-recovery-probe-3.jsonl.

The first two production scheduler processes recorded:

Scheduler PID	Completed HTTP responses	Retries	Errors	Median header wait	Maximum header wait
1725463	23 / 23	0	0	5.870 s	15.299 s
1727860	11 / 11	0	0	4.457 s	7.250 s

The sample is bounded at the audit read; it is not a service-availability SLA. Raw timing records: continuation-runs/transport-1725463.jsonl and continuation-runs/transport-1727860.jsonl. These contain no credentials, prompts, source text or tool output.

Three consecutive actual model turns returned turn.completed and exit 0:

Cycle	Task	Commands	File-change events	Turn seconds	Request failure	Local budget flag
4986	Periodic optimization	18	6	423.176	No	No
4987	FW-P6-FPA-Y	16	0	77.052	No	Yes
4988	FW-P6-FPA-Y	9	2	85.060	No	Yes

Cycle 4986 performed real TechDraw source repairs, incremental building, artifact synchronization and native business checks. Browser schema failures were retained as unfinished business. Cycles 4987/4988 reached local execution budgets; they are evidence of completed model transport, not completed business tasks. Cycles 4989/4990 subsequently ran local pipelines without model logs.

Validation

Final combined regression run: 180 tests passed in 20.356 seconds. The active scheduler (PID 1727860) reached cycle 4995 with HTTP/1.1 transport enabled; its loaded source fingerprint matched the file on disk and its watchdog was watching.

Transport tests cover byte-for-byte request and streamed-response preservation, authentication forwarding without logging, bounded header-timeout retries, no retry after partial tool responses, compaction, redirects, authentication errors, rate limits and credential-free configuration. Scheduler regressions cover the existing workflow, cache reuse, session handling and watchdog behavior.

Inspect live status with python3 tools/show_freecad_web_scheduler.py and the modelTransport field. Model request recovery does not mark any CAD feature or unresolved business issue as complete.