feat: support named child runs that survive migration and resurrection by barjin · Pull Request #759 · apify/apify-sdk-js

barjin · 2026-09-30T09:44:41Z

Adds a runName option to Actor.start, startTask, call and callTask that reattaches to the recorded child run after a restart, and the Actor.childRuns getter to read them.

Closes #738, closes #740

…process

…Actor.childRuns()

…med out ones

…es restarts

github-actions · 2026-09-30T09:46:56Z

⚠️ There are broken links in the documentation.

See more at https://github.com/apify/apify-sdk-js/actions/runs/38527819404#summary-115732253368

barjin

A few ideas / comments where this implementation differs from the Orchestrator ⬇️

Co-authored-by: Martin Adámek <banan23@gmail.com>

`Date` and `URL` inputs were hashed as `{}` and function inputs were dropped, so inputs differing only in those values got the same checksum and the earlier run was resumed. Hash the JSON form `apify-client` sends instead, and sort keys by code units, as `localeCompare` depends on the locale.

B4nan · 2026-10-06T13:28:12Z

Lets compare this with apify/apify-sdk-python#1149

B4nan · 2026-10-06T15:11:01Z

Compared with the Python counterpart, which is split into apify/apify-sdk-python#1149 (named runs) and apify/apify-sdk-python#1151 (Actor.child_runs()):

	JS (this PR)	Python
Option	`runName`	`name`
Methods	`start`, `call`, `callTask`	`start`, `call` (no `call_task`)
KVS key	`CHILD_RUNS`	`APIFY_CHILD_RUNS`
Stored record	`runId, status, startedAt, checksum, history[{runId, status, startedAt}]`	`actorId, runId, previousRunIds`
Name reused for a different request	throws if the Actor/task or input differs	`ValueError` only if the actor ID differs, a new input is accepted
`ABORTED` / `TIMED-OUT`	replaced by a new run	resurrected (with build, memory, timeout and max charge passed on)
`ABORTING` / `TIMING-OUT`	a new run starts right away, while the old one is still finishing	waits for it to finish, then resurrects it
`FAILED` / run gone	new run, old one kept in history	same
Concurrent calls with the same name	per-name promise chain	per-name `asyncio.Lock`
`call` log on a resumed run	`fromStart: !resumed`	same, plus a status message watcher; a `SUCCEEDED` run returns without streaming
`childRuns()`	stored snapshot with the last observed status, no API calls	fetches every run from the API; `run: None` if it's gone
Malformed stored data	not checked	raises `ValueError`
Tests	unit	unit + e2e

Things we should settle across both SDKs:

KVS key and record format. These should match, so the stored data looks the same whichever SDK wrote it.
Resurrect or replace aborted/timed-out runs (your question above). Either way, we should wait out ABORTING / TIMING-OUT before starting a replacement, otherwise the old and new runs overlap.
Whether the name check compares input (JS) or just the Actor (Python).
Whether childRuns() fetches fresh status from the API.
Python has no named call_task yet.

vdusek · 2026-10-07T07:09:48Z

Python PRs (apify/apify-sdk-python#1149, apify/apify-sdk-python#1151) have been changed to match JS behavior in two places:

the option is now named run_name,
and call_task supports it as well.

I'm still thinking about the rest.

…tter

vdusek

See this separate comment #759 (comment).

vdusek · 2026-10-09T13:17:27Z

+            const trackedRun = tracked ? await client.run(tracked.runId).get() : undefined;
+
+            if (trackedRun && ['SUCCEEDED', 'READY', 'RUNNING'].includes(trackedRun.status)) {
+                await this.verifyRequest(runName, request);


The checksum is only checked on this reattach path, so a name whose recorded run failed or got lost accepts a different input, and the new checksum overwrites the old one. Python raises in that case too, so a name stays bound to one Actor/task + input. Which way we want to go?

✍️ Drafted by Claude Code

I'd prefer to only fail on a (wrong) reattach.

If the user calls await Actor.call('foo/bar', { foo: "baz" }, { runName: 'boo' }); and it gives him a run of the foo/bar Actor with { foo: "baz" }, everything's imo good and there's no reason to fail.

I'd keep the error only for situations when the runName call returns something different from a regular, non-runName call (e.g., reattaches to an existing run with a different input).

Makes sense, I agree. That was the last open point, so I guess I can approve it. Once this is merged, I'll make the same changes in the Python SDK.

vdusek · 2026-10-09T13:50:10Z

Compared with the Python counterpart (apify/apify-sdk-python#1149 for named runs, apify/apify-sdk-python#1151 for child_runs). Every row is now settled. On a replaced run with a different input, Python will be changed to match JS after this is merged.

Full comparison table:

Area	JS (this PR)	Python	Aligned	Notes
Option name	`runName`	`run_name`	✅	Python renamed `name` → `run_name`
Supported methods	`start`, `call`, `startTask`, `callTask`	`start`, `call`, `start_task`, `call_task`	✅	JS added `Actor.startTask()` in this PR (#764)
Record format	`runId, status, startedAt, checksum, history[]`	same	✅
Checksum	sha256 of sorted-key JSON of `{type, id, input}`	same, byte-equal	✅
Write timing	right after start	right after start	✅
`READY` / `RUNNING`	reattach	reattach	✅
`SUCCEEDED`	return as is	return as is	✅
`FAILED` / run gone	new run, old one moved to `history`	same	✅
`ABORTED` / `TIMED-OUT`	resurrected with the call's build, memory, timeout and max charge	same	✅	Agreed, see r4230501550
`ABORTING` / `TIMING-OUT`	waits for it to finish, then resurrects	same	✅	See r4230501533
`Actor.resurrect()`	added in #769	added in apify/apify-sdk-python#1165	✅
404 on the recorded run	retried for 3 s first	same	✅	See r4230501519
Different input, run reattached	throws	raises	✅	Applies to a resurrected run too
Different input, run replaced	allowed, checksum overwritten	raises, will be allowed as in JS	✅	Agreed to fail only on a reattach; Python follow-up after merge
Concurrent calls under one name	per-name lock	per-name lock	✅
`childRuns` API	sync getter, `Record<string, RunClient>`	sync property, `dict[str, RunClientAsync]`	✅	Python aligned in apify/apify-sdk-python#1151
Registry load	in `init()`	in `__aenter__`	✅
Custom `token` in `childRuns`	kept in-process, default client after migration	same	✅	ported from Python
History in `childRuns`	KVS record only	KVS record only	✅
Access before init	warns, returns `{}`	raises	✅	each SDK's existing convention, fine as is
Malformed record	throws at init	`ValueError` at init	✅
Max charge / `max_items`	forwarded to the start and to the resurrection	same	✅
Tests	unit + e2e (reattach and resurrect)	unit + e2e (reboot → reattach)	✅

Edit: updated on 2026-10-14

✍️ Drafted by Claude Code

`Actor.start`, `Actor.call`, `Actor.start_task` and `Actor.call_task` accept an optional `run_name`. Right after the child starts, the SDK records it in the default key-value store under `__ACTOR_CHILD_RUNS`. After a migration or resurrection of the parent, the same call finds the recorded run and reuses it: - `READY` / `RUNNING`: reattaches to it - `SUCCEEDED`: returns it as is - `ABORTED` / `TIMED-OUT`: resurrects it with the call's build, memory, timeout, `max_items` and max charge (an `ABORTING` / `TIMING-OUT` run is waited for first) - `FAILED`, or the run no longer exists: starts a new run and moves the old one to `history` The record has the same shape as in the JS SDK (apify/apify-sdk-js#759): `runId`, `status`, `startedAt`, `checksum` and `history`. The checksum covers the Actor or task ID and the input, computed the same way as in JS. Reusing a name for a different Actor, task or input raises `ValueError`. Concurrent calls under one name in the same process share a single run. A named `call` on a reattached or resurrected run streams only new log lines. If the API reports a recorded run as missing, the SDK retries for 3 seconds before replacing it, because a run started moments ago may not be on every API replica yet. A hard kill between the platform starting the child and the registry write can still orphan the child. Closing that gap needs an idempotency key on the run-start endpoint. Closes: #1127 *✍️ Drafted by Claude Code*

`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*

# Conflicts: # src/actor.ts

… them Runs that are still aborting or timing out are awaited first, as only finished runs can be resurrected. The resurrection gets the build, memory, run timeout and limits of the call.

A run started moments ago may not be on every API replica yet, so a single 404 could start a duplicate run.

…ns after a reboot

Enables oxlint's `import/extensions` rule, so a relative import without the `.js` extension fails lint. `src` is already covered by `NodeNext` resolution, but `test/tsconfig.json` uses `Bundler` and lets these through (see #759 (comment)). Package imports are ignored, and master passes with the rule on.

barjin · 2026-10-14T09:17:04Z

All the discrepancies between Python and JS implementation have been cleared in the recent commits.

The last difference is the behaviour on failed / lost runs (see thread here and vote).

vdusek

LGTM 🚀

(I just updated the PR title to start with a verb.)

janbuchar

LGTM, it seems to have convinced Vláďa's LLM assistant

All the points from this review have been resolved.

Follow-up to #1149 and #1151 that aligns named child runs with the final version of apify/apify-sdk-js#759. Changes: - A different Actor, task or input under an existing `run_name` raises a `ValueError` only when the recorded run would be reused (reattached, returned as `SUCCEEDED`, or resurrected). When the recorded run `FAILED` or is gone, a new run starts with the new request, the old run moves to `history`, and the record takes the new checksum ([agreed here](apify/apify-sdk-js#759 (comment))). - The client of a named run is stored only after the run is started or reused. - The `run_name` docstrings describe the new rule. No action on [B4nan's comment](apify/apify-sdk-js#759 (comment)) about loading the child-run record lazily instead of in Actor init. JS kept the load in `init()`, because the synchronous `Actor.childRuns` getter needs the records, and Python already loads them the same way in `__aenter__`. The docs in #1160 still say a name is bound to its first input. That will be fixed there. *✍️ Drafted by Claude Code*

barjin added 10 commits September 30, 2026 10:54

feat: resumable start and call implementions

187354e

fix: do not resume child runs that are aborting or timing out

30114ed

refactor: move ChildRunTracker to its own file

075b9f7

feat: reject reusing a child run name for a different request in one …

c3c0718

…process

feat: resurrect aborted child runs and expose tracked child runs via …

3162daa

…Actor.childRuns()

refactor: start a new child run instead of resurrecting aborted or ti…

81815f2

…med out ones

docs: describe the public ChildRunTracker methods

a337bb0

style: use multiline jsdoc for ChildRunTracker methods

c9922a1

refactor: simplify child run tracking

1940b86

feat: persist the child run request checksum so the name check surviv…

7751f4c

…es restarts

barjin commented Sep 30, 2026

View reviewed changes

Comment thread src/actor.ts Outdated

Comment thread src/child_run_tracker.ts

Comment thread src/actor.ts Outdated

barjin self-assigned this Sep 30, 2026

barjin marked this pull request as ready for review September 30, 2026 09:55

barjin requested review from B4nan and janbuchar September 30, 2026 09:55

This was linked to issues Sep 30, 2026

Named child runs that survive migration and resurrection #738

Closed

Expose tracked child runs as a readable API #740

Closed

apify-service-account added tested Temporary label used only programatically for some analytics. t-tooling Issues with this label are in the ownership of the tooling team. labels Sep 30, 2026

B4nan reviewed Oct 5, 2026

View reviewed changes

Comment thread src/actor.ts Outdated

Comment thread src/child_run_tracker.ts

Comment thread src/child_run_tracker.ts

Comment thread src/child_run_tracker.ts Outdated

Comment thread src/actor.ts

barjin and others added 4 commits October 6, 2026 13:35

docs: extend the JSDoc for the runName option

f4cfdc4

Co-authored-by: Martin Adámek <banan23@gmail.com>

fix: clear trackedRuns cache on a KVS load error

29f7d13

Co-authored-by: Martin Adámek <banan23@gmail.com>

fix: add a per-name mutex for named run start and tracking

ca71dd2

Co-authored-by: Martin Adámek <banan23@gmail.com>

barjin requested a review from B4nan October 6, 2026 12:56

vdusek mentioned this pull request Oct 7, 2026

Add Actor.resurrect() apify/apify-sdk-python#1162

Closed

feat: expose tracked child runs as a synchronous Actor.childRuns ge…

8143fd7

…tter

vdusek mentioned this pull request Oct 9, 2026

feat: add Actor.child_runs with clients for named child runs apify/apify-sdk-python#1151

Merged

vdusek reviewed Oct 9, 2026

View reviewed changes

B4nan previously requested changes Oct 9, 2026

View reviewed changes

B4nan mentioned this pull request Oct 9, 2026

chore: enforce file extensions in relative imports #770

Merged

barjin added 9 commits October 12, 2026 10:59

chore: address nits

476b800

fix: forward signal and timeoutSecs in named call and callTask

ec5e6fa

Merge remote-tracking branch 'origin/master' into feat/track-child-runs

56034c3

# Conflicts: # src/actor.ts

feat: resurrect aborted and timed out child runs instead of replacing…

be2e911

… them Runs that are still aborting or timing out are awaited first, as only finished runs can be resurrected. The resurrection gets the build, memory, run timeout and limits of the call.

docs: clarify that a replaced child run accepts a different input

0741f7e

fix: look a missing child run up again before treating it as lost

68d44f2

A run started moments ago may not be on every API replica yet, so a single 404 could start a duplicate run.

feat: support runName in Actor.startTask()

9b52b8b

feat: validate the stored child runs when loading them

d6be7e8

test: add an e2e test for reattaching and resurrecting named child ru…

a1a5ef7

…ns after a reboot

barjin requested review from B4nan, janbuchar and vdusek October 14, 2026 09:11

vdusek approved these changes Oct 14, 2026

View reviewed changes

vdusek changed the title ~~feat: named child runs that survive migration and resurrection~~ feat: support named child runs that survive migration and resurrection Oct 14, 2026

janbuchar approved these changes Oct 15, 2026

View reviewed changes

barjin merged commit 9235254 into master Oct 15, 2026
12 checks passed

barjin deleted the feat/track-child-runs branch October 15, 2026 09:01

vdusek mentioned this pull request Oct 15, 2026

chore: align named child runs with the JS SDK apify/apify-sdk-python#1184

Merged

Conversation

barjin commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

barjin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

B4nan commented Oct 6, 2026

Uh oh!

B4nan commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vdusek commented Oct 7, 2026

Uh oh!

vdusek left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vdusek Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

barjin Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

vdusek Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vdusek commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

barjin commented Oct 14, 2026

Uh oh!

vdusek left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janbuchar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

barjin commented Sep 30, 2026 •

edited

Loading

github-actions Bot commented Sep 30, 2026 •

edited

Loading

B4nan commented Oct 6, 2026 •

edited

Loading

vdusek left a comment •

edited

Loading

vdusek commented Oct 9, 2026 •

edited

Loading

vdusek left a comment •

edited

Loading