tractor/ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.md

Prompt

Driver prompt file ai/prompt-io/prompts/issue_477.md:

attempt to resolve https://github.com/goodboy/tractor/issues/477 do it with /open-wkt.

(plus a hard stop-for-human-review deadline of 12:50PM EST the same day)

Issue #477 asks to factor ActorNursery.run_in_actor() (and possibly Portal.run()) out of the nursery internals into a new tractor.to_actor wrapper subpackage of “higher level one shot” single-remote-task APIs, adopting the trio.to_thread/anyio.to_process parlance, so that error collection/propagation moves up into the caller’s local trio scope and the nursery’s spawn machinery can eventually drop the ._ria_nursery coupling.

Response summary

First-cut tractor.to_actor subpkg delivering the one-shot API composed purely from the existing daemon-spawn + portal primitives (start_actor() + Portal.run() + Portal.cancel_actor()), leaving the legacy .run_in_actor() machinery untouched (formal deprecation deferred until in-repo usage migrates):

• to_actor.run(fn, **fn_kwargs) -> Any: spawn a subactor, schedule fn as its lone remote task, wait on and return its result, ALWAYS reaping the subactor (shield-safe finally). Remote errors raise in the caller’s task as boxed RemoteActorErrors.
• placement variants: portal= reuses a running actor (no spawn/reap), an= spawns from a caller-managed actor-nursery, neither opens a call-scoped private open_nursery() (implicitly booting the runtime, configurable via runtime_kwargs).
• fail-fast validation before any spawn: non-streaming async fn required; portal=/an= mutually exclusive; runtime_kwargs rejected alongside any placement opt.
• run_in_actor() TODO/docstring now cross-reference the successor API.

Files changed

• tractor/to_actor/__init__.py — new subpkg, re-exports run
• tractor/to_actor/_api.py — run() + _invoke_in_subactor() + _validate_one_shot_fn()
• tractor/__init__.py — top-level to_actor re-export
• tractor/runtime/_supervise.py — comment/docstring pointers from run_in_actor() to the successor
• tests/test_to_actor.py — 11-test suite covering all placement variants, error relay, the concurrent worker-pool-ish pattern and arg validation
• examples/parallelism/to_actor_one_shots.py — runnable demo (auto-collected by test_docs_examples.py)

Human edits

None yet — pending human review (work paused before the 12:50PM EST deadline per the driver prompt).