[Bug] Python SDK: Session.run() hangs forever when the runtime stalls — request_timeout_seconds doesn't bound the turn

[wangjianyuweg]

简述（中文）：Python SDK 的 Session.run() 在 runtime 收到 prompt 后卡住时会永久挂起——request_timeout_seconds 只约束 session/prompt 请求-响应，不约束整个 turn。已实测复现，修复方案见文末链接。

Problem

Session.run()'s event-collection loop (python/sdk/src/deepseek_harness/api.py) blocks on subscription.next(), which is queue.get() with no deadline. request_timeout_seconds only bounds the session/prompt request-response exchange (client.py, _request_raw); nothing bounds the turn itself.

When the runtime accepts the prompt, emits the agent/inbox/spliced receipt, and then stalls — a hung model HTTP call, a runtime deadlock, or any state where the process stays alive but session.status: idle never arrives — harness.run() blocks forever: no exception, no recovery short of killing the host process, and the runtime subprocess stays alive too.

The same permanent hang occurs when the receipt's inserted[].id doesn't match the prompt response's messageId: the received gate then discards every notification, including idle.

Repro

A fake runtime that answers initialize + session/prompt, emits the receipt, then goes silent — with request_timeout_seconds=1.0 configured:

{
  "runtime_pid": 18552,
  "thread_alive_past_request_timeout": true,
  "proc_alive_past_request_timeout": true,
  "thread_alive_after_6s": true,
  "proc_alive_after_6s": true
}

harness.run() was still blocked 6.8 s later (and stays blocked indefinitely), runtime subprocess alive. Happy to provide the full repro script.

Repro output screenshot:

Proposed fix

• New optional DeepSeekHarnessConfig.turn_timeout_seconds (default None keeps current behavior).
• Session.run() computes a wall-clock deadline, passes the remaining time to NotificationSubscription.next(timeout=...), and on expiry returns with finish_reason="timeout" (real turn/end kinds still win when present), preserving the events collected so far.

I've pushed a working fix with regression tests to my fork (PRs appear disabled on this repo, so linking the branch directly):

• Branch: https://github.com/wangjianyuweg/deepseek-harness/tree/fix/sdk-turn-timeout
• Diff vs upstream master: master...wangjianyuweg:deepseek-harness:fix/sdk-turn-timeout

With the fix, the repro above returns in 3.05 s with finish_reason='timeout' at the configured bound. Tests: python/sdk/tests/test_turn_timeout.py — stalled runtime returns timeout instead of hanging; slow-but-alive runtime without the option still completes normally.