Python: fix(core): refuse SecretString at checkpoint encode with a precise error

[Yufeng He (he-yufeng)]

Fixes #9514.

Why

Since #8127, SecretString is an immutable, slots-based, non-str wrapper with no __reduce__/__getstate__, so pickle protocols >= 2 dump it fine and fail at restore when the BUILD step hits the immutability guard. The checkpoint codec pickles every non-JSON-native value, so a credential in executor/session state could not round-trip: FileCheckpointStorage.save() refused it with the save-time restore check from #8214, but as an opaque decode failure (Failed to decode pickled checkpoint data: SecretString is immutable.), and Cosmos / Foundry-hosted storage share the codec without that check, so save() succeeded and only load() failed later. The obvious workaround (unwrap to str first) writes the raw secret into the checkpoint in cleartext.

What changed

One check in the codec's pickle funnel (_encode_pickle): a SecretString now raises a WorkflowCheckpointException at encode time saying why (unpicklable by design; a working pickle would persist the credential in cleartext) and what to do instead (keep credentials out of checkpointed state and re-resolve them from settings or configuration on restore). This matches the durable session-state path, which already rejects the type with a precise error via _validate_durable_state_value (#8874), and because the refusal lives in the shared codec it fires at save time on every backend, closing the Cosmos load-time asymmetry.

Scope notes: a SecretString nested in a plain dict or list is caught by the same recursion; one buried in a custom object still fails the save-time round-trip check with the generic wrapper, unchanged from before. Checkpoints already persisted with an embedded credential still fail at load with the wrapped decode error; they were never loadable, this change only moves the failure earlier and makes it legible.

Tests

• test_checkpoint_encode.py: direct value, dict-nested, and list-nested SecretString all raise the precise error at encode; all three go red if the check is removed (mutation-verified).
• test_checkpoint.py: FileCheckpointStorage.save() surfaces the precise error unwrapped, proving the except WorkflowCheckpointException: raise pass-through keeps the message intact.
• The issue's repro shape run standalone against this tree now produces the precise save-time error instead of the opaque decode one.
• Full test_checkpoint_encode.py + test_checkpoint.py green (114 passed); the other checkpoint suites green except two test_restricted_decode_allows_openai* failures that reproduce identically on pristine main in this environment (stale openai package in the local venv, unrelated). pyright clean on the touched module.

[Copilot]

🟡 Changes recommended

Whole-dictionary pickle fallbacks still bypass rejection, allowing credential-bearing checkpoints to be saved by Cosmos but not restored.

1 open issue

• Nested SecretString values bypass protection in pickle fallback · New

What changed in this PR

Addresses #9514 by rejecting SecretString during checkpoint encoding with actionable guidance instead of an opaque restore error.

Changes:

• Adds a guard in the shared pickle encoder.
• Tests direct and nested secrets and File storage error propagation.

File	Description
python/​packages/​core/​tests/​workflow/​test_checkpoint.py	Tests save-time error propagation.
python/​packages/​core/​tests/​workflow/​test_checkpoint_encode.py	Tests direct, dict-nested, and list-nested rejection.
python/​packages/​core/​agent_framework/​_workflows/​_checkpoint_encoding.py	Adds explicit credential rejection and recovery guidance.

_{Review effort: Balanced}