feat: add Actor.child_runs with clients for named child runs (#1151)

`Actor.child_runs` is a sync property that maps each run name to a
`RunClientAsync` for the current run under that name. It has the same
shape as `Actor.childRuns` in the JS SDK (apify/apify-sdk-js#759). The
client covers the run and its storages:

```python
run = await Actor.child_runs['scrape-eu'].wait_for_finish()
```

The SDK reads the registry from the default key-value store when the
Actor initializes, so runs recorded before a migration or resurrection
are included and reading the property makes no API calls. That adds one
record read to every init. A malformed record fails the init and leaves
the Actor uninitialized. Runs started without a `run_name` aren't
tracked. Runs that were replaced under a name stay in the `history` of
the `__ACTOR_CHILD_RUNS` record and aren't exposed.

A run started or reattached with a custom `token` gets a client with
that token. A run recorded before a migration and not reattached since
gets the default client, because the token isn't stored.

It also fixes a duplicate `max_items` deprecation warning from #1149: a
named start that resurrects its recorded run no longer warns a second
time from inside the SDK.

Docs are in #1160.

Closes: #1129

*✍️ Drafted by Claude Code*

Author: vdusek

src/apify/_actor.py

@@ -182,6 +182,7 @@ async def __aenter__(self) -> Self:
         - Sets up local or cloud storage clients depending on whether the Actor runs locally or on the Apify platform.
         - Configures the event manager and starts periodic state persistence.
         - Initializes the charging manager for handling charging events.
+        - Loads the named child runs recorded by an earlier attempt of this Actor run.
         - Configures logging after all core services are registered.
 
         This method must be called exactly once per Actor instance. Re-initializing an Actor or having multiple
@@ -230,9 +231,20 @@ async def __aenter__(self) -> Self:
         # Mark initialization as complete and update global state.
         self._active = True
 
-        if not Actor.is_at_home():
-            # Make sure that the input related KVS is initialized to ensure that the input aware client is used
-            await self.open_key_value_store()
+        try:
+            if not Actor.is_at_home():
+                # Make sure that the input related KVS is initialized to ensure that the input aware client is used
+                await self.open_key_value_store()
+
+            await self._child_run_registry.load()
+        except BaseException:
+            # Undo the initialization, since a failed `__aenter__` gets no `__aexit__`.
+            self._active = False
+            try:
+                await self._charging_manager_implementation.__aexit__(None, None, None)
+            finally:
+                await self.event_manager.__aexit__(None, None, None)
+            raise
         return self
 
     async def __aexit__(
@@ -384,6 +396,24 @@ def apify_client(self) -> ApifyClientAsync:
             self._apify_client = self.new_client()
         return self._apify_client
 
+    @property
+    @_ensure_context
+    def child_runs(self) -> dict[str, RunClientAsync]:
+        """Clients for the named child runs of this Actor run, keyed by the run name.
+
+        Every run started by `Actor.start`, `Actor.call`, `Actor.start_task` or `Actor.call_task` with a `run_name` is
+        included, even one started before a migration or resurrection of this Actor run. Runs started without a
+        `run_name` are not tracked. Each client points to the current run under its name:
+
+        ```python
+        run = await Actor.child_runs['my-child'].wait_for_finish()
+        ```
+
+        A run started or reattached with a custom `token` since the last migration or resurrection of this Actor run
+        uses that token. Any other run uses the default client.
+        """
+        return self._child_run_registry.run_clients(self.apify_client)
+
     @cached_property
     def configuration(self) -> Configuration:
         """Actor configuration, uses the default instance if not explicitly set."""
@@ -1026,7 +1056,6 @@ async def start(
             run_input=run_input,
             client=client,
             start_run=start_run,
-            token=token,
             build=build,
             max_items=max_items,
             max_total_charge_usd=max_total_charge_usd,
@@ -1230,7 +1259,6 @@ async def call(
                     force_permission_level=force_permission_level,
                     webhooks=to_client_representations(webhooks),
                 ),
-                token=token,
                 build=build,
                 max_items=max_items,
                 max_total_charge_usd=max_total_charge_usd,
@@ -1257,7 +1285,6 @@ async def _find_or_start_child_run(
         run_input: Any,
         client: ApifyClientAsync,
         start_run: Callable[[], Awaitable[Run]],
-        token: str | None,
         build: str | None,
         max_items: int | None,
         max_total_charge_usd: Decimal | None,
@@ -1272,15 +1299,13 @@ async def _find_or_start_child_run(
             run_input=run_input,
             client=client,
             start_run=start_run,
-            resurrect_run=partial(
-                self.resurrect,
-                token=token,
+            resurrect_run=lambda run_id: client.run(run_id).resurrect(
                 build=build,
+                memory_mbytes=memory_mbytes,
+                run_timeout=self._resolve_run_timeout(timeout),
                 max_items=max_items,
                 max_total_charge_usd=max_total_charge_usd,
                 restart_on_error=restart_on_error,
-                memory_mbytes=memory_mbytes,
-                timeout=timeout,
             ),
         )
 
@@ -1391,7 +1416,6 @@ async def start_task(
             run_input=task_input,
             client=client,
             start_run=start_run,
-            token=token,
             build=build,
             max_items=max_items,
             max_total_charge_usd=max_total_charge_usd,
@@ -1492,7 +1516,6 @@ async def call_task(
                     run_timeout=self._resolve_run_timeout(timeout),
                     webhooks=to_client_representations(webhooks),
                 ),
-                token=token,
                 build=build,
                 max_items=max_items,
                 max_total_charge_usd=max_total_charge_usd,

src/apify/_child_runs.py

@@ -104,6 +104,8 @@ def __init__(self, open_key_value_store: Callable[[], Awaitable[KeyValueStore]])
         """Guards loading the records and writing them back to the key-value store."""
         self._name_locks: WeakValueDictionary[str, asyncio.Lock] = WeakValueDictionary()
         """Serializes `find_or_start` per name. A lock is dropped once no call under its name holds it."""
+        self._clients: dict[str, ApifyClientAsync] = {}
+        """Client the run under each name was last started or looked up with. Lost on a migration."""
 
     async def find_or_start(
         self,
@@ -140,18 +142,20 @@ async def find_or_start(
             records = await self._load()
             record = records.get(name)
 
-            if record is None:
-                run = await self._start(name, checksum=checksum, start_run=start_run, history=[])
-                return run, True
-
-            if record.checksum != checksum:
+            if record is not None and record.checksum != checksum:
                 raise ValueError(
                     f'The run name "{name}" was already used for a different Actor, task or input. '
                     'Use a unique `run_name` for each child run.'
                 )
 
+            if record is None:
+                run = await self._start(name, checksum=checksum, start_run=start_run, history=[])
+                self._clients[name] = client
+                return run, True
+
             run_client = client.run(record.run_id)
             run = await _get_recorded_run(run_client)
+            self._clients[name] = client
 
             if run is not None and run.status in _SETTLING_STATUSES:
                 run = await run_client.wait_for_finish()
@@ -176,6 +180,21 @@ async def find_or_start(
             await self.update(name, run)
             return run, False
 
+    def run_clients(self, default_client: ApifyClientAsync) -> dict[str, RunClientAsync]:
+        """Return a client for the current run under each recorded name.
+
+        Each client comes from the client its name was last started or looked up with in this process, so a run started
+        with a custom token uses that token.
+
+        Args:
+            default_client: Client used for a name not started or looked up in this process, e.g. one recorded before a
+                migration.
+        """
+        return {
+            name: self._clients.get(name, default_client).run(record.run_id)
+            for name, record in (self._records or {}).items()
+        }
+
     async def update(self, name: str, run: Run) -> None:
         """Record the latest observed status of the run recorded under `name`.
 
@@ -203,20 +222,23 @@ async def _start(
         await self._save(name, record)
         return run
 
-    async def _load(self) -> dict[str, ChildRunRecord]:
+    async def load(self) -> dict[str, ChildRunRecord]:
+        """Read the records from the default key-value store, replacing any read before."""
         async with self._lock:
-            if self._records is None:
-                key_value_store = await self._open_key_value_store()
-                stored = await key_value_store.get_value(CHILD_RUNS_KEY)
-                try:
-                    self._records = _records_adapter.validate_python(stored or {})
-                except ValidationError as exc:
-                    raise ValueError(
-                        f'The child run registry under the "{CHILD_RUNS_KEY}" key in the default key-value store '
-                        'is malformed.'
-                    ) from exc
+            key_value_store = await self._open_key_value_store()
+            stored = await key_value_store.get_value(CHILD_RUNS_KEY)
+            try:
+                self._records = _records_adapter.validate_python(stored or {})
+            except ValidationError as exc:
+                raise ValueError(
+                    f'The child run registry under the "{CHILD_RUNS_KEY}" key in the default key-value store '
+                    'is malformed.'
+                ) from exc
             return self._records
 
+    async def _load(self) -> dict[str, ChildRunRecord]:
+        return self._records if self._records is not None else await self.load()
+
     async def _save(self, name: str, record: ChildRunRecord) -> None:
         records = await self._load()
         key_value_store = await self._open_key_value_store()

tests/e2e/test_actor_child_runs.py

@@ -13,7 +13,7 @@ async def test_named_child_run_is_reattached_after_reboot(
     make_actor: MakeActorFunction,
     run_actor: RunActorFunction,
 ) -> None:
-    """A named child run started before a reboot is reattached and awaited by a named call after it."""
+    """A named child run started before a reboot is listed after it and reattached by a named call."""
 
     async def main() -> None:
         async with Actor:
@@ -31,6 +31,10 @@ async def main() -> None:
                 await Actor.reboot()
                 return
 
+            child_runs = Actor.child_runs
+            assert child_runs.keys() == {'child'}, f'child_runs={child_runs}'
+            assert child_runs['child'].resource_id == child_run_id, f'child_runs={child_runs}'
+
             run = await Actor.call(actor_id=actor_id, run_input={'is_child': True}, run_name='child')
             assert run is not None, 'run is None'
             assert run.id == child_run_id, f'run.id={run.id}, child_run_id={child_run_id}'