pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/fleet/client.py

@@ -0,0 +1,569 @@
+"""The worker's one door to the platform: the gateway over HTTP, on its fleet's key."""
+
+import asyncio
+import base64
+import json
+import logging
+import time
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Iterator,
+    Mapping,
+    Sequence,
+)
+
+import httpx
+from opentelemetry import propagate
+from pydantic import TypeAdapter
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed, InvalidHandshake
+
+from pinecall.domain.agent import AgentConfig
+from pinecall.domain.call import Route
+from pinecall.domain.errors import GatewayRefused
+from pinecall.domain.names import Channel, Json, JsonObject
+from pinecall.domain.scope import Scope
+from pinecall.wire.frames import Command, Entry
+from pinecall.wire.parts import PlatformTool, ToolResult
+from pinecall.wire.rest.agents import HoldAudio, RingHandoff
+from pinecall.wire.rest.calls import (
+    AppendEntriesRefused,
+    AppendEntriesRequest,
+    AppendEntriesResponse,
+    BatchedEntry,
+    CallbackRequest,
+    LogPage,
+    OpenCallRequest,
+    OpenCallResponse,
+    RecordingKeyResponse,
+    SealCallRequest,
+)
+from pinecall.wire.rest.fleet import HeartbeatRequest, HeartbeatResponse
+from pinecall.wire.rest.numbers import LegTrunk, LegTrunkResponse
+
+logger = logging.getLogger(__name__)
+
+
+# A caller is waiting on the line.
+TIMEOUT_S = 5.0
+
+
+# A clip is a few hundred KB, fetched once per box.
+A_FILE_S = 15.0
+
+
+# Under the job's sealing budget (worker/main.py); what does not seal here the reaper seals. One
+# knock waits all of it: a seal writes memory and asks the judges, which outlast TIMEOUT_S.
+SEALED_WITHIN_S = 30.0
+
+# The header a balancer keeps a call's requests on one gateway by: `/v1/calls/{call}/...`.
+CALL_HEADER = "Pinecall-Call"
+CALL_AT = 3
+
+
+# A restarting gateway is back in seconds; the cap keeps the log catching up after it.
+FIRST_WAIT_S = 0.5
+
+
+LONGEST_WAIT_S = 5.0
+
+
+SAID_EVERY = 10
+
+
+NOT_SERVED = 404
+
+
+ALREADY_OVER = 409
+
+
+# A caller is waiting on the line while the open is asked again.
+OPENED_WITHIN_S = 15.0
+
+
+# The socket a call's batches go down: `WS /v1/calls/{call}/entries`.
+STREAM_DOOR = "/v1/calls/{call}/entries"
+
+
+EVENT_STREAM = "text/event-stream"
+
+
+_ROUTES: TypeAdapter[list[Route]] = TypeAdapter(list[Route])
+
+
+_CONFIG: TypeAdapter[AgentConfig] = TypeAdapter(AgentConfig)
+
+
+_OBJECT: TypeAdapter[JsonObject] = TypeAdapter(JsonObject)
+
+
+class GatewayClient:
+    """The gateway as a worker asks it: every door it knocks, on one connection pool."""
+
+    def __init__(self, http: httpx.AsyncClient) -> None:
+        """No call opened yet."""
+        self.http = http
+        # What each unsealed call was opened with, said again to a gateway that restarted.
+        self.opened: dict[str, OpenCallRequest] = {}
+        # Each unsealed call's socket for its batches; none once a gateway had no such door.
+        self.streams: dict[str, EntriesStream] = {}
+        self.doorless = False
+
+    # ── an agent, before its call ──
+
+    async def routes(
+        self, scope: Scope | None, *, number: str | None, channel: Channel
+    ) -> list[Route]:
+        """The routes of the dispatch's scope; with no scope, the one a number rings, any org."""
+        params = _scope_headers(scope)
+        if number is not None:
+            params |= {"number": number, "channel": channel}
+        return _ROUTES.validate_python(await self._read("GET", "/v1/routes", params=params))
+
+    # The call, not opened yet, is named so a canary's share is picked by its id.
+    async def agent(self, slug: str, scope: Scope, *, call: str | None = None) -> AgentConfig:
+        """The agent as the scope runs it for the call: its declaration under the settings."""
+        params = _scope_headers(scope) | ({} if call is None else {"for_call": call})
+        text = await self._read("GET", f"/v1/agents/{slug}/config", params=params)
+        return _CONFIG.validate_python(text)
+
+    # The one answer that carries keys, and it carries them to the fleet's key alone.
+    async def stages(self, slug: str, scope: Scope, *, call: str | None = None) -> Json:
+        """The three stages the call runs, each with the key it runs on."""
+        params = _scope_headers(scope) | ({} if call is None else {"for_call": call})
+        return await self._read("GET", f"/v1/agents/{slug}/provider-keys", params=params)
+
+    async def hold_audio(self, slug: str, scope: Scope) -> HoldAudio:
+        """What the agent plays while a tool runs."""
+        text = await self._read(
+            "GET", f"/v1/agents/{slug}/hold-audio", params=_scope_headers(scope)
+        )
+        return HoldAudio.model_validate(text)
+
+    async def hold_clip(self, slug: str, scope: Scope) -> bytes:
+        """The org's own clip, Ogg Opus."""
+        path = f"/v1/agents/{slug}/hold-audio/audio"
+        answer = await self._answered("GET", path, None, A_FILE_S, _scope_headers(scope))
+        return answer.content
+
+    async def rings_for(self, slug: str, org: str, caller: str) -> RingHandoff:
+        """Whether a production ring from this phone belongs in a developer's sandbox."""
+        params = {"org": org, "caller": caller}
+        text = await self._read("GET", f"/v1/agents/{slug}/rings-for", params=params)
+        return RingHandoff.model_validate(text)
+
+    # The gateway judges the leg (shape and pace) and names the trunk; a refusal is its sentence.
+    async def leg(
+        self, slug: str, scope: Scope, *, to: str, call: str, shown: str | None
+    ) -> LegTrunk:
+        """How to dial a leg of the call: the trunk inline and the number shown."""
+        params = (
+            _scope_headers(scope) | {"to": to, "call": call} | ({"from": shown} if shown else {})
+        )
+        text = await self._read("GET", f"/v1/agents/{slug}/outbound-trunk", params=params)
+        return LegTrunkResponse.model_validate(text).trunk
+
+    # A cold transfer dials nothing of ours, so no trunk: the gateway judges the leg alone.
+    async def sent_on(self, slug: str, scope: Scope, *, to: str, call: str) -> None:
+        """Have the gateway judge a cold transfer's leg; its refusal is its sentence."""
+        params = _scope_headers(scope) | {"to": to, "call": call}
+        await self._read("POST", f"/v1/agents/{slug}/cold-transfer", params=params)
+
+    # ── a call ──
+
+    # Asked again while the gateway is away: an open is the same call by its id (one claim, one
+    # opening, one ringing), so an answer lost with a gateway that died is not a call lost.
+    async def open(self, opening: OpenCallRequest) -> OpenCallResponse:
+        """Open the call's log; the answer is what the org's minutes leave it."""
+        body = opening.written()
+        data = await again(lambda: self._read("POST", "/v1/calls", body), OPENED_WITHIN_S, "open")
+        self.opened[opening.context.call] = opening
+        return OpenCallResponse.model_validate(data)
+
+    # Retried without a limit, the same batch after the same count: the log answers a batch it
+    # already took with the seqs it gave it, so an answer lost never writes an entry twice. The
+    # batches go down one socket per call; a gateway of before has no such door, and from the
+    # first that says so every call's batches go by request.
+    async def append_many(
+        self, call: str, entries: Sequence[BatchedEntry], *, after: int
+    ) -> list[Entry]:
+        """Write a batch of the call's entries once, in order; the gateway numbers them."""
+        path = STREAM_DOOR.format(call=call)
+        if not self.doorless:
+            stream = self.streams.get(call) or self._stream_of(call)
+            numbered = await again(
+                lambda: self._streamed_batch(call, stream, entries, after), None, path
+            )
+            if numbered is not None:
+                return numbered
+            self.doorless = True
+            self.streams.pop(call, None)
+        body = AppendEntriesRequest(after=after, entries=list(entries)).written()
+        door = f"/v1/calls/{call}/entries"
+        answer = await again(lambda: self._on_the_call(call, "POST", door, body), None, door)
+        return AppendEntriesResponse.model_validate(answer).entries
+
+    # The gateway answers a lapsed tool at its own deadline: wait past it, so the model reads
+    # that answer and not a timeout of ours. Idempotent per call id, so a retry joins.
+    async def tool(self, call: str, agent: str, called: JsonObject, timeout_s: float) -> ToolResult:
+        """Run a tool in the app that declared it and return what it answered."""
+        waiting = timeout_s + TIMEOUT_S
+        path = f"/v1/calls/{call}/tools?agent={agent}"
+        answer = await again(
+            lambda: self._on_the_call(call, "POST", path, called, waiting), waiting, path
+        )
+        return ToolResult.model_validate(answer)
+
+    async def sealed(self, call: str, sealing: SealCallRequest) -> None:
+        """Hand the end of the call to the gateway, which prices, judges and seals it."""
+        path = f"/v1/calls/{call}/sealed"
+        body = sealing.written()
+        try:
+            await again(
+                lambda: self._on_the_call(call, "POST", path, body, SEALED_WITHIN_S),
+                SEALED_WITHIN_S,
+                path,
+            )
+        except GatewayRefused as refused:
+            # Sealed already: by this seal, whose answer a gateway that died took with it.
+            if refused.answered != ALREADY_OVER:
+                raise
+        self.opened.pop(call, None)
+        await self._stream_closed(call)
+
+    async def lookup(
+        self, call: str, tool: PlatformTool, arguments: Mapping[str, Json], speech: str | None
+    ) -> JsonObject:
+        """Recall or search, run by the gateway, which writes what it found on the log."""
+        data: JsonObject = {"tool": tool, "input": dict(arguments), "speech_id": speech}
+        answer = _OBJECT.validate_python(
+            await self._on_the_call(call, "POST", f"/v1/calls/{call}/lookup", data)
+        )
+        return _OBJECT.validate_python(answer.get("output") or {})
+
+    # Asked once, at the call's end: a gateway away leaves the recording plain, never unsealed
+    # waiting. A gateway of before sealed recordings has no such door and answers 404.
+    async def recording_key(self, call: str) -> bytes | None:
+        """The key the call's recording is sealed under; None from a gateway that seals none."""
+        try:
+            answer = await self._on_the_call(call, "POST", f"/v1/calls/{call}/recording/key")
+        except GatewayRefused as refused:
+            if refused.answered != NOT_SERVED:
+                raise
+            return None
+        return base64.urlsafe_b64decode(RecordingKeyResponse.model_validate(answer).key)
+
+    # A code nobody issued is an ordinary answer: the caller may be dialling an extension.
+    async def claim(self, call: str, code: str) -> bool:
+        """Tie the call to the page showing the code; False when no page waits on it."""
+        try:
+            await self._on_the_call(call, "POST", f"/v1/calls/{call}/claim", {"code": code})
+        except GatewayRefused as refused:
+            if refused.answered != NOT_SERVED:
+                raise
+            return False
+        return True
+
+    async def state(self, call: str) -> JsonObject:
+        """The call's state as the gateway folds it, with the seq it was folded to."""
+        return _OBJECT.validate_python(
+            await self._on_the_call(call, "GET", f"/v1/calls/{call}/state")
+        )
+
+    async def since(self, call: str, after: int) -> AsyncIterator[Entry]:
+        """The stored entries above the cursor, page by page, until the log's end."""
+        cursor = after
+        while True:
+            path = f"/v1/calls/{call}/events?after={cursor}"
+            page = await again(lambda p=path: self._read("GET", p), SEALED_WITHIN_S, path)
+            if page is None:
+                return
+            read = LogPage.model_validate(page)
+            for entry in read.entries:
+                yield Entry.model_validate(entry)
+            if read.next is None:
+                return
+            cursor = read.next
+
+    async def tail(self, call: str, after: int) -> AsyncIterator[Entry]:
+        """The entries above the cursor, then the live ones, until the call ends."""
+        async for frame in self._streamed(f"/v1/calls/{call}/events?after={after}"):
+            yield Entry.model_validate(frame)
+
+    # A stream that ends means the gateway went away; a 404 means it forgot the call.
+    async def commands(self, call: str) -> AsyncGenerator[Command]:
+        """The app's commands for the call, in the order it sent them, until the call is sealed."""
+        path = f"/v1/calls/{call}/commands"
+        try:
+            async for frame in self._streamed(path):
+                yield Command.model_validate(frame)
+        except GatewayRefused as refused:
+            if not await self._reopened(call, refused):
+                raise
+        else:
+            return
+        async for frame in self._streamed(path):
+            yield Command.model_validate(frame)
+
+    # ── the fleet ──
+
+    async def heartbeat(self, beat: HeartbeatRequest) -> HeartbeatResponse:
+        """Report this worker; the answer says whether it is cordoned."""
+        return HeartbeatResponse.model_validate(
+            await self._read("POST", "/v1/fleet/heartbeat", beat.written())
+        )
+
+    async def callback(self, wanted: CallbackRequest) -> None:
+        """Somebody the overflow told to wait for a call back."""
+        await self._read("POST", "/v1/callbacks", wanted.written())
+
+    async def aclose(self) -> None:
+        """Close every call's socket and the connection pool."""
+        for call in list(self.streams):
+            await self._stream_closed(call)
+        await self.http.aclose()
+
+    # ── the wire ──
+
+    async def _read(
+        self,
+        method: str,
+        path: str,
+        data: Json = None,
+        wait_s: float | None = None,
+        params: Mapping[str, str] | None = None,
+    ) -> Json:
+        answer = await self._answered(method, path, data, wait_s, params)
+        return answer.json() if answer.content else None
+
+    async def _answered(
+        self,
+        method: str,
+        path: str,
+        data: Json,
+        wait_s: float | None,
+        params: Mapping[str, str] | None,
+    ) -> httpx.Response:
+        try:
+            answer = await self.http.request(
+                method,
+                path,
+                json=data,
+                timeout=wait_s or TIMEOUT_S,
+                params=params or None,
+                headers={**traced(), **affine(path)},
+            )
+        except httpx.HTTPError as unreachable:
+            raise GatewayRefused(f"{method} {path}: {unreachable}") from unreachable
+        if answer.status_code >= httpx.codes.BAD_REQUEST:
+            raise GatewayRefused(
+                f"{method} {path}: {answer.status_code} {answer.text}", answered=answer.status_code
+            )
+        return answer
+
+    # A 404 for a call this worker opened is a gateway that restarted: say the call again, once.
+    async def _on_the_call(
+        self, call: str, method: str, path: str, data: Json = None, wait_s: float | None = None
+    ) -> Json:
+        try:
+            return await self._read(method, path, data, wait_s)
+        except GatewayRefused as refused:
+            if not await self._reopened(call, refused):
+                raise
+        return await self._read(method, path, data, wait_s)
+
+    def _stream_of(self, call: str) -> "EntriesStream":
+        path = STREAM_DOOR.format(call=call)
+        base = str(self.http.base_url).rstrip("/")
+        url = f"ws{base.removeprefix('http')}{path}"
+        # The key alone of the pool's headers: its keep-alive and encodings are not a handshake's.
+        bearer = self.http.headers.get("Authorization")
+        headers = {**({"Authorization": bearer} if bearer else {}), **traced(), **affine(path)}
+        stream = EntriesStream(url, headers, call)
+        self.streams[call] = stream
+        return stream
+
+    # A 404 on the socket is the gateway that forgot the call, as on a request; None is a gateway
+    # with no such door at all, which the batch door serves.
+    async def _streamed_batch(
+        self, call: str, stream: "EntriesStream", entries: Sequence[BatchedEntry], after: int
+    ) -> list[Entry] | None:
+        try:
+            return await stream.append_many(entries, after=after)
+        except GatewayRefused as refused:
+            if stream.doorless:
+                return None
+            if not await self._reopened(call, refused):
+                raise
+        return await stream.append_many(entries, after=after)
+
+    async def _stream_closed(self, call: str) -> None:
+        stream = self.streams.pop(call, None)
+        if stream is not None:
+            await stream.close()
+
+    async def _reopened(self, call: str, refused: GatewayRefused) -> bool:
+        opening = self.opened.get(call)
+        if refused.answered != NOT_SERVED or opening is None:
+            return False
+        await self._read("POST", f"/v1/calls/{call}/reopened", opening.written())
+        return True
+
+    async def _streamed(self, path: str) -> AsyncIterator[JsonObject]:
+        try:
+            async with self.http.stream(
+                "GET", path, headers={"Accept": EVENT_STREAM, **affine(path)}, timeout=STREAMED
+            ) as stream:
+                if stream.status_code >= httpx.codes.BAD_REQUEST:
+                    raise GatewayRefused(
+                        f"GET {path}: {stream.status_code}", answered=stream.status_code
+                    )
+                async for frame in server_sent(stream.aiter_lines()):
+                    yield frame
+        except httpx.HTTPError as unreachable:
+            raise GatewayRefused(f"GET {path}: {unreachable}") from unreachable
+
+
+# One batch is out at a time (the call's writer sends the next when this one is answered), so an
+# answer is the last frame sent. An answer that does not come within the request's timeout is
+# not waited for past it: the socket is dropped, and the retry asks again on a new one.
+class EntriesStream:
+    """A call's batches down one WebSocket to the gateway, each answered with its seqs."""
+
+    def __init__(self, url: str, headers: Mapping[str, str], call: str) -> None:
+        """Not connected yet: the first batch connects."""
+        self.url = url
+        self.headers = dict(headers)
+        self.call = call
+        self.socket: ClientConnection | None = None
+        # True once the gateway refused the upgrade: it has no such door.
+        self.doorless = False
+        self._sending = asyncio.Lock()
+
+    async def append_many(self, entries: Sequence[BatchedEntry], *, after: int) -> list[Entry]:
+        """Send the batch and read its answer; GatewayRefused when the socket or the log did."""
+        frame = AppendEntriesRequest(after=after, entries=list(entries)).model_dump_json()
+        async with self._sending:
+            socket = await self._connected()
+            try:
+                await socket.send(frame)
+                raw = await asyncio.wait_for(socket.recv(), TIMEOUT_S)
+            except (ConnectionClosed, OSError, TimeoutError) as lost:
+                await self.close()
+                raise GatewayRefused(f"WS {self.url}: {lost}") from lost
+        answer = json.loads(raw)
+        if isinstance(answer, dict) and "refused" in answer:
+            refused = AppendEntriesRefused.model_validate(answer)
+            raise GatewayRefused(
+                f"WS {self.url}: {refused.status} {refused.refused}", answered=refused.status
+            )
+        return AppendEntriesResponse.model_validate(answer).entries
+
+    async def close(self) -> None:
+        """Close the socket; the next batch opens another."""
+        socket, self.socket = self.socket, None
+        if socket is not None:
+            await socket.close()
+
+    async def _connected(self) -> ClientConnection:
+        if self.socket is not None:
+            return self.socket
+        try:
+            self.socket = await connect(
+                self.url, additional_headers=self.headers, open_timeout=TIMEOUT_S
+            )
+        except InvalidHandshake as refused:
+            self.doorless = True
+            raise GatewayRefused(f"WS {self.url}: {refused}", answered=NOT_SERVED) from refused
+        except (OSError, TimeoutError) as unreachable:
+            raise GatewayRefused(f"WS {self.url}: {unreachable}") from unreachable
+        return self.socket
+
+
+# A stream is timed only on connect: a quiet one is kept open by the gateway's ping every 25 s.
+STREAMED = httpx.Timeout(TIMEOUT_S, read=None)
+
+
+def gateway_at(url: str, key: str | None) -> GatewayClient:
+    """The gateway at this URL, knocked on with the fleet's key in the header, never the URL."""
+    headers = {"Authorization": f"Bearer {key}"} if key else {}
+    return GatewayClient(httpx.AsyncClient(base_url=url, headers=headers, timeout=TIMEOUT_S))
+
+
+# `data:` holds the whole entry, its seq and type included: `id:`, `event:` and comments are
+# not read.
+async def server_sent(lines: AsyncIterator[str]) -> AsyncIterator[JsonObject]:
+    """Each JSON message of a server-sent event stream."""
+    data: list[str] = []
+    async for raw in lines:
+        line = raw.rstrip("\r\n")
+        if line.startswith("data:"):
+            data.append(line[5:].lstrip(" "))
+        elif not line and data:
+            text = json.loads("\n".join(data))
+            data = []
+            if isinstance(text, dict):
+                yield text
+
+
+def waits() -> Iterator[float]:
+    """The waits between tries: doubling from half a second to five."""
+    wait = FIRST_WAIT_S
+    while True:
+        yield wait
+        wait = min(wait * 2, LONGEST_WAIT_S)
+
+
+def away(refused: GatewayRefused) -> bool:
+    """Whether the gateway is away (unreachable or a 5xx), which a retry outlasts."""
+    return refused.answered is None or refused.answered >= httpx.codes.INTERNAL_SERVER_ERROR
+
+
+# A 4xx is an answer. `within_s` bounds a request that has a deadline (a tool); None retries for
+# as long as the call lasts (an entry).
+async def again[T](attempt: Callable[[], Awaitable[T]], within_s: float | None, what: str) -> T:
+    """Run the attempt, retrying while the gateway is away and there is time left."""
+    started = time.monotonic()
+    pauses = waits()
+    tries = 0
+    while True:
+        tries += 1
+        try:
+            return await attempt()
+        except GatewayRefused as refused:
+            pause = next(pauses)
+            late = within_s is not None and time.monotonic() - started + pause > within_s
+            if not away(refused) or late:
+                raise
+            if tries % SAID_EVERY == 0:
+                logger.warning("%s: the gateway is still away after %d tries", what, tries)
+            await asyncio.sleep(pause)
+
+
+# The worker's current span rides each request as W3C traceparent, so the gateway's handling of an
+# append joins the turn's trace; with no tracer set (no PINECALL_OTLP_ENDPOINT) nothing is added.
+def traced() -> dict[str, str]:
+    """The headers that carry the current trace to the gateway; none when nothing traces."""
+    carried: dict[str, str] = {}
+    propagate.inject(carried)
+    return carried
+
+
+# A box of several gateways hashes this header at its balancer, so a call's doors land on one
+# gateway while it lives: its first sights, its sequencer's fills and its writers stay rare. Only
+# a speed-up: any gateway serves any door, and an old worker sends none.
+def affine(path: str) -> dict[str, str]:
+    """The header naming the call a door is about, when its path names one."""
+    parts = path.split("/")
+    if len(parts) > CALL_AT and parts[1:CALL_AT] == ["v1", "calls"] and parts[CALL_AT]:
+        return {CALL_HEADER: parts[CALL_AT]}
+    return {}
+
+
+def _scope_headers(scope: Scope | None) -> dict[str, str]:
+    if scope is None:
+        return {}
+    return {"org": scope.org, "env": scope.env, "holder": scope.holder}

pinecall/fleet/demand.py

@@ -0,0 +1,51 @@
+"""How many scaled workers a fleet wants: the one rule Kubernetes sizes the burst by."""
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+from fractions import Fraction
+
+from pinecall.fleet.roster import heard_lately
+from pinecall.wire.rest.fleet import WorkerStatus
+
+
+@dataclass(frozen=True)
+class Line:
+    """Where a fleet is kept: the busy target, the slack under it, how many, and their seats."""
+
+    # Grow above `target`; shrink only below `target - slack`, so two asks do not oscillate.
+    target: float = 0.6
+    slack: float = 0.15
+    at_least: int = 0
+    at_most: int = 10
+    # PINECALL_MAX_JOBS of a scaled worker: what one more of them adds.
+    seats_per_worker: int = 4
+
+
+# A cluster's workers that scale (their names start with `scaled`) are sized by Kubernetes, which
+# asks this number, counting the seats of the workers that do not scale (a core node's) first, so
+# a call they hold asks for no scaled one. Grow to what brings busy under the target; let one go
+# only when busy stays under target - slack without it; else hold. Absolute, so a pod still
+# booting, not yet heard, is never asked for twice.
+def wanted_scaled(
+    seats: Sequence[WorkerStatus], scaled: str, line: Line, now: float
+) -> tuple[int, int, int]:
+    """How many scaled workers the fleet wants now, its calls, and the seats it holds."""
+    counted = [seat for seat in seats if heard_lately(seat, now) and seat.max_jobs is not None]
+    holding = [seat for seat in counted if not seat.cordoned]
+    active = sum(seat.active for seat in counted)
+    fixed = sum(seat.max_jobs or 0 for seat in holding if not seat.worker.startswith(scaled))
+    current = sum(1 for seat in holding if seat.worker.startswith(scaled))
+    each = line.seats_per_worker
+    # The target's decimal as written: 6 / 0.6 in floats is 10.000000000000002, one seat too many.
+    needed = math.ceil(Fraction(active) / Fraction(str(line.target))) - fixed
+    grown = max(0, math.ceil(Fraction(needed) / each)) if needed > 0 else 0
+    capacity = fixed + current * each
+    if grown > current:
+        return min(grown, line.at_most), active, capacity
+    left = fixed + (current - 1) * each
+    # With no call one may always go; with calls, only if the seats left keep busy under the slack.
+    quiet = active == 0 or (left > 0 and active / left < line.target - line.slack)
+    if current > max(grown, line.at_least) and quiet:
+        return current - 1, active, capacity
+    return current, active, capacity