Distribute the parent's maxTotalChargeUsd across child runs

[B4nan]

A pay-per-event orchestrator started with maxTotalChargeUsd has no help keeping its children inside that budget. Each child accepts its own max_total_charge_usd, but splitting the parent's remaining budget across children, adjusting as earlier children finish under their cap, is left to the caller. The orchestrator skill (apify/agent-skills#90) lists this as a must-have, which means agents are currently writing it themselves.

Depends on #1127: the reservations live in the child run registry, and only the registry knows the children after a restart.

Proposal

Treat a child's cap as a reservation against the parent's budget:

• remaining = parent limit − parent's own charge so far − Σ caps of tracked children that are still running
• a named child started without an explicit max_total_charge_usd gets remaining; an explicit value is capped at remaining. The cap is recorded in the registry when the child starts.
• when a child reaches a terminal state, release cap − actual charge (from the run's usage_total_usd) back to the budget

Caps are known locally at start time, so the limit holds however many children start concurrently, and recursively for grandchildren since each child's subtree is bounded by its own cap. The delayed cost feed only affects the release step; being late there under-allocates for a while, which is the safe direction.

ChargingManager is the natural owner: it already knows the parent's own charge and limit.

Out of scope

A budget shared across unrelated runs (a "BudgetPool", see the discussion below). In the SDK it would race on a KVS record without compare-and-swap and depend on the delayed cost feed for every decision. The platform has authoritative usage per run, so that belongs there, next to the idempotency key on run start and the parent/child run link.

✍️ Drafted by Claude Code

[Pijukatel]

Just thinking out loud. If I understand this correctly, this will work well for one child's Actor trees or one child at a time scenarios. But when one actor spawns multiple children at the same time, this will no longer be capable of upholding the limit. Each child will get the remaining actor limit, and if all of them use it, then we are above the limit again.

If a shared limit is desired, we would have to introduce some shared resource. Some sort of "BudgetPool". Even without platform support, we could hack something just in the SDK - but it would suffer from whatever API delay is on the cost information.

Such a BudgetPool could be persistent - based on named storage or temporary - based on unnamed storage.
Such a BudgetPool could not only serve as cost synchronization, but also as a more detailed cost tracking record - you could inspect it and see which actor contributed by which amount.

You could even use one BudgetPool for unrelated Actors' runs by just pointing it to the same storage, which would open quite interesting options for managing the usage of the platform.

On top of it, if the budget pool is based on storages, it can also be emulated locally.

Where to integrate it? Maybe as an optional internal component of either the Actor or the ChargingManager.

[B4nan]

Good catch, the "remaining" default breaks under fan-out. It should be a reservation instead: remaining = parent limit − parent's own charge − Σ caps of children still running; a new child gets min(requested, remaining) and that cap is reserved in the registry when it starts; on a terminal state, release cap − actual. Caps are known locally at start time, so the limit holds however many children start at once, and recursively for grandchildren. The delayed cost feed only affects the release step, and being late there is conservative. I'll update the proposal.

A shared BudgetPool across unrelated runs is a separate feature. Doing it on storages in the SDK has two problems: KVS has no compare-and-swap, so concurrent writers race on the pool record and overspend silently, and every decision depends on the delayed cost feed rather than just the release. The platform already has authoritative usage per run, so I'd file the pool as a platform follow-up alongside the idempotency key and parent/child link rather than build it here.

Agree ChargingManager is the right owner for the reservation logic, it already knows the parent's own charge and limit.

[Pijukatel]

Yes, we have limited options without platform support.

This is a somewhat related proposal https://app.notion.com/p/apify/WIP-ChargingGroups-tokens-with-usage-limit-367f39950a2280438df6eabcba27a66f

[B4nan]

Priority note: the Billing team has a Q4 KR to enforce the maximum cost across the whole run chain on the platform side, which covers this. The SDK should pass max_total_charge_usd through and otherwise do nothing. The reservation scheme above is a fallback only if the platform support doesn't land in Q4. Keeping the issue open in the epic at low priority until that's known.