feat(python): expose Bash class with Monty Python execution and external function handler

[shubhlohiya]

Summary

The crates/bashkit-python PyO3 bindings expose BashTool and ScriptedTool but not the
Bash builder API. The Rust python feature (Monty embedded interpreter) and
python_with_external_handler are available at the Rust level but unreachable from Python.

This PR adds a Bash Python class that exposes both, making it possible to:

1. Run Python code via python3/python builtins (Monty embedded interpreter)
2. Register named external functions that Python code can call as ordinary functions, dispatched
   to an async Python handler

Usage

from bashkit import Bash

# Plain bash (unchanged behaviour)
bash = Bash()
result = await bash.execute("echo hello")

# Bash + embedded Python execution
bash = Bash(python=True)
result = await bash.execute("python3 -c 'x = 6 * 7; print(x)'")
# result.stdout == "42"

# Bash + Python + external function handler
async def handler(fn_name: str, args: list, kwargs: dict) -> Any:
    if fn_name == "fetch":
        return {"status": "ok", "value": 42}
    raise ValueError(f"Unknown function: {fn_name}")

bash = Bash(
    python=True,
    external_functions=["fetch"],
    external_handler=handler,
)
result = await bash.execute(
    "python3 -c \"d = fetch(); print(d['status'], d['value'])\""
)
# result.stdout == "ok 42"

Changes

• Cargo.toml — enable python feature; add num-bigint dep for BigInt round-trip
• src/lib.rs:
  • Extend PyBash constructor with three new optional params: python: bool,
    external_functions: list[str] | None, external_handler: AsyncCallable | None
  • Extract make_external_handler and apply_python_config helpers shared between
    new() and reset()
  • Fix reset() to preserve python mode and external handler config (previously dropped)
  • Raise ValueError when external_functions is supplied without external_handler
  • Add monty_to_py / py_to_monty conversion helpers covering all MontyObject variants,
    including correct BigInt ↔ Python int round-trip and PyTuple support
• _bashkit.pyi — update stub with new constructor params, ExternalHandler Protocol
  for precise type checking, and cancel() method
• tests/test_bashkit.py — 19 new tests; all 336 tests pass

All existing BashTool and ScriptedTool behaviour is unchanged.

---

🤖 Generated with Claude Code

[shubhlohiya]

Hey @chaliy , I've been using bashkit in a Python agent project and needed to expose the Monty Python execution and external function handler from the Rust side to Python. I made the changes on my fork and they're working well for my use case. I wanted to check if you'd be open to merging this back upstream? Happy to iterate on the implementation if anything needs adjusting.

[chaliy]

@shubhlohiya yep, sounds totally missed feature. I will look at it in next couple of hous and if all good, will merge it. Thank you!

[Copilot]

Pull request overview

This PR extends the crates/bashkit-python PyO3 bindings so Python users can configure the core Bash interpreter to enable Monty embedded Python execution (python=True) and optionally register external function names that dispatch to an async Python handler.

Changes:

• Extend Bash (PyBash) constructor/reset to support python, external_functions, and external_handler.
• Add MontyObject ⇄ Python conversion helpers, including BigInt round-tripping.
• Update Python stubs and add tests covering Python mode + external handler behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
crates/bashkit-python/src/lib.rs	Adds Python/external-handler configuration and conversion glue for Monty interop.
crates/bashkit-python/tests/test_bashkit.py	Adds tests for python execution, external handler dispatch, reset behavior, and BigInt conversion.
crates/bashkit-python/bashkit/_bashkit.pyi	Updates type stubs for new Bash constructor options, ExternalHandler Protocol, and cancel().
crates/bashkit-python/Cargo.toml	Enables bashkit’s python feature and adds num-bigint dependency.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[shubhlohiya]

Fixed — reset() now clears the shared cancellation flag after rebuilding the interpreter so cancel() does not erroneously abort post-reset executions.

[chaliy]

Rechecked on the current head (36dd822) and this is still reproducible. Clearing the old flag avoids an immediate abort, but cancel() is still wired to the pre-reset token rather than the rebuilt Bash instance. Minimal repro on the updated extension:

bash = Bash(python=True)
bash.reset()
bash.cancel()
result = await bash.execute("echo hi")

After reset(), that returns exit_code == 0 with stdout == "hi\n"; without reset(), the same pre-cancelled execute returns execution cancelled. So the binding still needs to refresh self.cancelled (or otherwise route cancel() to the current inner interpreter token), and the new test only checks that cancel() does not raise.

[shubhlohiya]

Fixed properly in 9617a09 — the cancellation token is now wrapped in Arc<RwLock<Arc<AtomicBool>>> so reset() swaps it to the new interpreter's token and cancel() always reads the current one. Applies to both Bash and BashTool.

Verified with your repro:

bash = Bash(python=True)
bash.reset()
bash.cancel()
result = await bash.execute("echo hi")
# exit_code=1, stderr="execution cancelled"  ✓

Also added tests for both directions (cancel-then-reset clears, reset-then-cancel targets new interpreter). 342 tests pass.

[shubhlohiya]

Fair point — relaxed to ^0.4.6 to allow compatible patch bumps.

[shubhlohiya]

Added — cancel() was already implemented on BashTool in Rust, just missing from the stub. Drive-by fix.

[shubhlohiya]

The built wheel is ~3.5 MB with the python feature enabled. I think the size/build-time impact is small enough that it is not worth the added complexity of a conditional Cargo feature, but happy to revisit if the maintainer feels differently.

[chaliy]

This bridge rewrites both MontyObject::Set and MontyObject::FrozenSet to PyList, so a Python external_handler sees a different type than the Monty caller passed. I reproduced this on the built extension with echo_type({1, 2}): the handler received list, not set. That silently changes semantics for supported Monty container types instead of preserving them or failing explicitly when an element is unhashable.

[shubhlohiya]

Fixed — monty_to_py now produces PySet/PyFrozenSet directly and propagates the error if items are unhashable, rather than silently falling back to a list.

[chaliy]

One more issue on the current head (36dd822): BashTool still has the same reset/cancel token bug as Bash, but that code path is outside the changed hunks so I could not attach it inline.

Repro against the updated extension:

tool = BashTool()
tool.reset()
tool.cancel()
result = await tool.execute("echo hi")

That still succeeds with exit_code == 0 / stdout == "hi\n", so BashTool.reset() is rebuilding the inner Bash without refreshing self.cancelled to the new interpreter token. Since this PR also adds cancel() to the BashTool stub, it would be good to fix that reset/cancel path too and add a regression test for pre-cancel after reset.

[shubhlohiya]

@chaliy , addressed in 9617a09