[hetaoBackend]

Change

Fixes four bugs in the Python SDK (minimax-code-sdk, import name minimax_code, package packages/code-sdk-python) that are present in the published 0.1.0b1 and on main, plus three related documentation/safety issues. All changes are confined to packages/code-sdk-python. The package version is not bumped; the fixes are recorded under a new ## Unreleased CHANGELOG section (the release check still reads the first dated heading).

BUG-1 (medium-high): leaving async for early did not stop the CLI and left the Thread busy

StreamedTurn.__aiter__ returned the inner async generator. Python never calls aclose() on an async generator when the loop is left with break or an exception in the loop body (PEP 525), and streamed.events kept it alive, so the CLI kept running and every later Turn on the same Thread raised ThreadBusyError. That contradicts the README, the CHANGELOG and the StreamedTurn docstring.

Fix: __aiter__ now returns a small _TurnIterator. When it is dropped without being exhausted (break / exception in the body), it starts closing the Turn in the background (SIGINT, then SIGKILL after the grace period). StreamedTurn.aclose() now goes through one shared close task, so the background close and an explicit aclose() / async with exit never race on the generator. Thread._start waits for an in-progress close of the previous Turn before deciding the Thread is busy, so break followed immediately by await thread.run(...) works. thread.run(), async with streamed, explicit aclose() and SyncThread.run_streamed keep their behavior.

BUG-2 (medium): the timeout_ms backstop was reported as a cancellation

When the CLI ignored its own timeout and the SDK backstop (timeout_ms + 30 s) killed it with SIGKILL, the negative exit code was mapped to MCodeAbortError("The MCode run was cancelled."), so callers could not tell a timeout from a cancel.

Fix: the backstop now records that it fired (_Exec.kill_for_timeout), and error_for_exit(..., timed_out=True) raises MCodeRunError(status="timeout") with the message "The MCode run exceeded timeout_ms and was force-stopped by the SDK.", matching the TypeScript SDK (exec-process.ts, backstopFired).

BUG-3 (low): incomplete results raised a bare KeyError

An exec.completed result without durationMs raised KeyError: 'durationMs' in Thread.run, and a failed result whose error lacked message raised KeyError: 'message' in error_for_result. Neither is caught by except MCodeError, although the README says all errors subclass MCodeError.

Fix: a successful result without an integer durationMs raises MCodeProtocolError; error_for_result reads message/category defensively and still raises MCodeRunError (falling back to "status ").

BUG-4 (low): SDK errors did not survive pickling

MCodeRunError could not be unpickled (TypeError: missing keyword-only argument 'status') and an unpickled ThreadBusyError repeated its message, because Exception.__reduce__ rebuilds with cls(*self.args). This breaks multiprocessing, ProcessPoolExecutor and Celery-style workers.

Fix: MCodeError.__reduce__ rebuilds via cls.__new__(cls, *args) and restores the instance attributes, so every subclass round-trips with its type, message and fields (status, category, exit_code, stderr, ...).

Related items

• a. Accepted (code fix). repr(MCodeOptions(...)) printed the whole env dict, so env=dict(os.environ) could put API keys into logs. MCodeOptions.__repr__ now shows only the variable names with every value replaced by ***. Masking all values instead of guessing which names look secret avoids missed keys.
• b. Accepted (documentation fix). The README said events are passed through unchanged, but an item.updated snapshot identical to the previous snapshot of the same item is skipped (intentional, same as the TypeScript SDK's items.ts). The README and CHANGELOG now describe this; behavior is unchanged.
• c. Accepted (documentation fix, no code change). The CHANGELOG said SyncMCode works in notebooks, but inside a running event loop (Jupyter) it raises RuntimeError: Cannot run the event loop while another loop is running. The CHANGELOG, README and sync.py docstring now say the blocking API cannot be used where a loop is already running and point to the async API. The SDK does not pretend to support it.

The README "Cancellation" section also documents that the next Turn waits for an abandoned Turn to shut down, and that the backstop raises MCodeRunError(status="timeout").

Validation

• Revision: this branch, based on main at 6e062ae. Environment: macOS arm64, project-local uv virtual environments.
• cd packages/code-sdk-python && uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -W error: all checks pass, mypy strict clean, 44 passed, 3 skipped (the 3 skips are the opt-in e2e tests). Same result on Python 3.10.20 and 3.13.
• New regression tests in tests/test_sdk.py (with new hang, no_duration and error_no_message scenarios in tests/fake_mcode.py): test_break_without_aclose_stops_cli_and_frees_thread, test_exception_in_loop_body_stops_cli_and_frees_thread, test_timeout_backstop_raises_timeout_error, test_incomplete_results_raise_sdk_errors (x2), test_errors_survive_pickling, test_options_repr_hides_env_values. With src/ reverted to main, all 7 fail; with this change, all pass.
• Standalone reproduction scripts (each with its own fake CLI, no real mcode, no credentials), run with PYTHONPATH=packages/code-sdk-python/src:
  • BUG-1: before, CLI child still alive 2 s after break: True, then ThreadBusyError on the next run. After, alive: False; a run started immediately after break starts a new CLI instead of raising ThreadBusyError; the exception-in-body case behaves the same.
  • BUG-2: before, MCodeAbortError | The MCode run was cancelled. | exit_code -9. After, MCodeRunError | The MCode run exceeded timeout_ms and was force-stopped by the SDK. | exit_code -9 | status: timeout.
  • BUG-3: before, KeyError: 'durationMs' / KeyError: 'message'. After, MCodeProtocolError / MCodeRunError.
  • BUG-4: before, TypeError for MCodeRunError and a doubled ThreadBusyError message. After, both round-trip with type, message and attributes intact.
• An external 65-test acceptance suite (L1 install/import, L2 API contract, L3 offline fake-CLI behavior), run against a wheel built from this branch: 65 passed, 0 failed (on 0.1.0b1 it had 6 failures, all mapped to BUG-1..4).
• node scripts/source-inventory.mjs: public source check passed. No files were added, removed or renamed.
• uv run python scripts/release_check.py metadata: version metadata is consistent (0.1.0b1).
• Performance: basic. Only the Python SDK changes; no CLI, TUI or desktop code is touched.
• NOT RUN: the end-to-end tests against a real mcode CLI and model (-m e2e); Windows (the SDK uses terminate() instead of SIGINT there); Linux was not run locally, but the Python SDK CI matrix covers ubuntu and macOS. The full monorepo pnpm verify was not run because no TypeScript or release-contract files change. All results above are offline, fake-CLI results, not live-service acceptance.

Publication and contribution checks

• I have permission to contribute these changes under the existing licenses applicable to the changed files/packages; imported material and its provenance are identified and existing notices are preserved.
• No credentials, account data, real user content, internal source history or private review material is included.
• Added/removed source files were reviewed before regenerating release/public-source.json; new tests are declared in test/vitest-suites.json where applicable. (No files added or removed; Python tests are collected by pytest, not Vitest.)
• Shared English/Chinese documentation and capability/verification records are updated where applicable. Mock/offline results are not described as live-service acceptance. (The SDK README is English-only.)

Maintainer handoff

Publication scope or license changes (if any): none.

Shared-source port: pending. The Python SDK fixes should be ported back to the shared source. A follow-up 0.1.0b2 release is needed for PyPI users to get these fixes.

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}