---
model: claude-fable-5
service: claude
session: f6c84722-471a-4458-9a80-e453fea9029f
timestamp: 2026-07-02T15:42:55Z
git_ref: 65bf9df5
scope: code
substantive: true
raw_file: 20260702T154255Z_65bf9df5_prompt_io.raw.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 `RemoteActorError`s.
- 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).