pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/gateway/api/fleet.py

@@ -0,0 +1,73 @@
+"""The fleet doors: a worker's heartbeat, and LiveKit's word on a room's people."""
+
+import time
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request
+
+from pinecall.channels import rooms
+from pinecall.channels.telephony.hand_over import unbridged
+from pinecall.domain.errors import NotAllowed
+from pinecall.domain.names import PRODUCTION, Env
+from pinecall.fleet import worlds
+from pinecall.fleet.demand import Line, wanted_scaled
+from pinecall.gateway._deps import FleetKey, GatewayDep, webhook_body
+from pinecall.gateway.dispatching.arrivals import arrived, settled
+from pinecall.gateway.ending.stranded import stranded
+from pinecall.wire.rest.fleet import HeartbeatRequest, HeartbeatResponse
+from pinecall.wire.rest.ops import FleetDemand
+
+router = APIRouter()
+
+UNSIGNED = "the event carries no Authorization: LiveKit signs every event it sends"
+
+
+@router.post("/v1/fleet/heartbeat")
+async def heartbeat(
+    body: HeartbeatRequest, _key: FleetKey, gateway: GatewayDep
+) -> HeartbeatResponse:
+    """A worker's report; the answer says whether it is cordoned and its fleet full."""
+    return gateway.roster.report(body, time.time())
+
+
+# KEDA's metrics-api scaler reads `wanted` and keeps the scaled Deployment at it (infra/charts),
+# asking with its world's fleet key, which names the fleet: one number needs no operator's key.
+@router.get("/v1/fleet/wanted")
+async def wanted_workers(
+    key: FleetKey,
+    gateway: GatewayDep,
+    scaled: Annotated[str, Query(min_length=1)],
+    seats: Annotated[int, Query(gt=0)],
+    most: Annotated[int, Query(gt=0)] = Line.at_most,
+) -> FleetDemand:
+    """How many workers whose names start with `scaled` the fleet wants, each of `seats` seats."""
+    fleet = worlds.fleet_of(await worlds.fleets(gateway.connections.pool), key.env)
+    line = Line(at_most=most, seats_per_worker=seats)
+    now = time.time()
+    wanted, active, capacity = wanted_scaled(gateway.roster.of(fleet, now), scaled, line, now)
+    return FleetDemand(fleet=fleet, wanted=wanted, active=active, seats=capacity)
+
+
+# livekit sends its token bare in Authorization, and every room event of the box: all but an
+# agent lost mid-call are answered and let be. Each world's LiveKit names its world in the URL
+# its config sends to, so the room is asked of the LiveKit it lives on.
+@router.post("/v1/livekit/webhook", status_code=204)
+async def receive_livekit_event(
+    request: Request, gateway: GatewayDep, world: Annotated[Env, Query()] = PRODUCTION
+) -> None:
+    """A room event LiveKit signed: a caller alone is offered a worker; an agent lost, told."""
+    # In this order: a worker gone sends the sentence, a caller alone is offered a worker, a room
+    # an agent joined or that ended is let go, and a room a hand-over bridges goes with either of
+    # its legs; each event moves one of the four.
+    token = request.headers.get("Authorization")
+    if not token:
+        raise NotAllowed(UNSIGNED)
+    settings = gateway.connections.settings
+    body = (await webhook_body(request)).decode()
+    event = rooms.livekit_event(
+        body, token, settings.livekit_api_key or "", settings.livekit_api_secret or ""
+    )
+    await stranded(gateway.serving, gateway.offering, world, event)
+    await arrived(gateway.offering, world, event)
+    await settled(gateway.offering, event)
+    await unbridged(gateway.offering.servers[world], event)

pinecall/gateway/api/hosting.py

@@ -0,0 +1,241 @@
+"""The hosting doors: the apps the box hosts for an org, their releases, and the org's secrets."""
+
+import asyncio
+from datetime import UTC, date, datetime, timedelta
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request, Response
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import parse_env
+from pinecall.gateway._deps import Acting, AppKey, GatewayDep, asked_by, capped_body
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy import admission, hosted_running, hosting, org_secrets
+from pinecall.tenancy.hosted_running import Served
+from pinecall.tenancy.hosting import HostedApp, Release
+from pinecall.tenancy.org_secrets import Secret
+from pinecall.wire.rest.hosting import (
+    AppLogsResponse,
+    HostedAppList,
+    HostedAppRow,
+    PutSecretRequest,
+    ReleaseList,
+    ReleaseRow,
+    RollbackRequest,
+    SecretList,
+    SecretRow,
+    ServedPage,
+    ServedRow,
+)
+
+router = APIRouter()
+
+
+GZIP = "application/gzip"
+
+
+ROLLED_BACK = "rollback to release {release}"
+
+
+NOT_A_MONTH = "{month!r} is not a month: YYYY-MM, like 2026-09"
+
+
+@router.get("/v1/hosted")
+async def list_hosted_apps(key: AppKey, gateway: GatewayDep) -> HostedAppList:
+    """The apps the box hosts for the org in this world, by name."""
+    listed = await hosting.apps_of(gateway.connections.pool, key.org, key.env)
+    return HostedAppList(
+        apps=[
+            HostedAppRow(
+                name=app.name,
+                release=app.release,
+                live_release=app.live_release,
+                failed_why=app.failed_why,
+                stopped=app.stopped,
+                created_by=app.created_by,
+                created_at=app.created_at.timestamp(),
+            )
+            for app in listed
+        ]
+    )
+
+
+# The body is the tarball, no multipart; the note rides the query. An app's first release is
+# what makes it: counted against the org's quota, and given the token its process will run on.
+@router.post("/v1/hosted/{name}/releases")
+async def upload_release(
+    name: str,
+    request: Request,
+    key: AppKey,
+    gateway: GatewayDep,
+    note: Annotated[str, Query(max_length=200)] = "",
+) -> ReleaseRow:
+    """The project's sources as the app's next release."""
+    pool = gateway.connections.pool
+    app = HostedApp(org=key.org, env=key.env, name=hosting.checked_name(name))
+    source = await asyncio.to_thread(
+        hosting.checked_source, await capped_body(request, hosting.LARGEST_SOURCE)
+    )
+    author = asked_by(key)
+    if not await hosting.is_hosted(pool, app):
+        hosted = len(await hosting.apps_of(pool, key.org, key.env))
+        await admission.admit_hosted_app(pool, key.org, key.env, hosting=hosted)
+        await hosting.open_app(pool, gateway.connections.vault, app, created_by=author)
+    kept = await hosting.keep_release(pool, app, source, author=author, note=note.strip())
+    return _release_row(app, kept)
+
+
+@router.get("/v1/hosted/{name}/releases")
+async def list_releases(name: str, key: AppKey, gateway: GatewayDep) -> ReleaseList:
+    """The app's releases, newest first."""
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    kept = await hosting.releases_of(gateway.connections.pool, app)
+    return ReleaseList(releases=[_release_row(app, release) for release in kept])
+
+
+@router.get("/v1/hosted/{name}/releases/{release}/source")
+async def release_source(name: str, release: int, key: AppKey, gateway: GatewayDep) -> Response:
+    """The tarball one release was uploaded as."""
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    source = await hosting.source_of(gateway.connections.pool, app, release)
+    return Response(source.data, media_type=GZIP)
+
+
+@router.post("/v1/hosted/{name}/stop", status_code=204)
+async def stop_hosted_app(name: str, key: AppKey, gateway: GatewayDep) -> None:
+    """Stop running the app: its process drains, and its releases and token stay."""
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    await hosted_running.stop_app(gateway.connections.pool, app, by=asked_by(key))
+
+
+@router.post("/v1/hosted/{name}/start", status_code=204)
+async def start_hosted_app(name: str, key: AppKey, gateway: GatewayDep) -> None:
+    """Run a stopped app again, its newest release."""
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    await hosted_running.start_app(gateway.connections.pool, app)
+
+
+@router.post("/v1/hosted/{name}/rollback")
+async def roll_back_release(
+    name: str, body: RollbackRequest, key: AppKey, gateway: GatewayDep
+) -> ReleaseRow:
+    """An earlier release's sources kept again as the app's next release."""
+    pool = gateway.connections.pool
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    source = await hosting.source_of(pool, app, body.release)
+    note = ROLLED_BACK.format(release=body.release)
+    kept = await hosting.keep_release(pool, app, source, author=asked_by(key), note=note)
+    return _release_row(app, kept)
+
+
+# The runner sends them on its next beat: a first ask answers what it sent last, or nothing.
+@router.get("/v1/hosted/{name}/logs")
+async def app_logs(name: str, key: AppKey, gateway: GatewayDep) -> AppLogsResponse:
+    """The last lines of the app's process, and the runner told to send them again."""
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    logs = await hosted_running.ask_for_logs(gateway.connections.pool, app)
+    return AppLogsResponse(
+        name=name,
+        host=logs.host,
+        lines=logs.lines,
+        at=None if logs.at is None else logs.at.timestamp(),
+    )
+
+
+@router.get("/v1/hosted/usage")
+async def hosted_usage(
+    key: AppKey, gateway: GatewayDep, month: Annotated[str | None, Query()] = None
+) -> ServedPage:
+    """The time the org's apps served here per UTC day, in one month: this one by default."""
+    since, until = month_of(month)
+    rows = await hosted_running.served(
+        gateway.connections.pool, since, until, org=key.org, env=key.env
+    )
+    return served_page(since, until, rows)
+
+
+@router.delete("/v1/hosted/{name}", status_code=204)
+async def drop_hosted_app(name: str, key: AppKey, gateway: GatewayDep) -> None:
+    """Stop hosting the app: its releases go, and its token is revoked."""
+    app = HostedApp(org=key.org, env=key.env, name=name)
+    await hosting.drop_app(gateway.connections.pool, app)
+
+
+@router.get("/v1/secrets")
+async def list_secrets(key: AppKey, gateway: GatewayDep) -> SecretList:
+    """The org's secrets in this world, by name; never a value."""
+    return await _secrets(gateway.connections.pool, key)
+
+
+@router.put("/v1/secrets/{name}")
+async def put_secret(
+    name: str, body: PutSecretRequest, key: AppKey, gateway: GatewayDep
+) -> SecretList:
+    """Keep one secret, sealed, replacing the value it had; the org's list after it."""
+    connections = gateway.connections
+    secret = Secret(env=key.env, name=name, value=body.value)
+    await org_secrets.put_secret(
+        connections.pool, connections.vault, key.org, secret, set_by=asked_by(key)
+    )
+    return await _secrets(connections.pool, key)
+
+
+@router.delete("/v1/secrets/{name}")
+async def drop_secret(name: str, key: AppKey, gateway: GatewayDep) -> SecretList:
+    """Forget one secret; the org's list after it, 404 for a name nobody set."""
+    pool = gateway.connections.pool
+    await org_secrets.drop_secret(pool, key.org, key.env, name)
+    return await _secrets(pool, key)
+
+
+def month_of(month: str | None) -> tuple[date, date]:
+    """The first day of the month named (YYYY-MM), or of this UTC one, and of the next."""
+    if month is None:
+        first = datetime.now(UTC).date().replace(day=1)
+    else:
+        try:
+            first = datetime.strptime(month, "%Y-%m").replace(tzinfo=UTC).date()
+        except ValueError:
+            raise DeclarationRefused(NOT_A_MONTH.format(month=month)) from None
+    after = (first.replace(day=28) + timedelta(days=4)).replace(day=1)
+    return first, after
+
+
+def served_page(since: date, until: date, rows: list[Served]) -> ServedPage:
+    """The time apps served, as the doors answer it."""
+    return ServedPage(
+        since=since.isoformat(),
+        until=until.isoformat(),
+        rows=[
+            ServedRow(
+                org=row.org,
+                env=parse_env(row.env),
+                name=row.name,
+                day=row.day.isoformat(),
+                seconds=round(row.seconds, 1),
+            )
+            for row in rows
+        ],
+    )
+
+
+async def _secrets(pool: Pool, key: Acting) -> SecretList:
+    listed = await org_secrets.secrets_of(pool, key.org, key.env)
+    return SecretList(
+        secrets=[
+            SecretRow(name=secret.name, set_by=secret.set_by, set_at=secret.set_at.timestamp())
+            for secret in listed
+        ]
+    )
+
+
+def _release_row(app: HostedApp, release: Release) -> ReleaseRow:
+    return ReleaseRow(
+        name=app.name,
+        release=release.release,
+        sha256=release.sha256,
+        bytes=release.bytes,
+        author=release.author,
+        note=release.note,
+        created_at=release.created_at.timestamp(),
+    )

pinecall/gateway/api/judges.py

@@ -0,0 +1,97 @@
+"""The judge doors: the org's questions for every agent's calls, and one agent's for its own."""
+
+import re
+
+from fastapi import APIRouter
+
+from pinecall.domain.agent import AgentJudge
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.scope import THE_ORGS_OWN
+from pinecall.gateway._deps import Acting, EvalsKey, GatewayDep
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy import judges
+from pinecall.tenancy.judges import StoredJudge
+from pinecall.wire.rest.evals import JudgeList, JudgeRequest, JudgeRow
+
+router = APIRouter()
+
+
+# The name call.score gives the verdict: lower-case words joined by hyphens.
+A_NAME = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+NOT_A_NAME = (
+    "{name!r} is not a judge's name: lower-case words joined by hyphens, like offers-next-slot"
+)
+
+
+# One list for both worlds, as the agent's personas are.
+@router.get("/v1/org/judges")
+async def list_org_judges(key: EvalsKey, gateway: GatewayDep) -> JudgeList:
+    """The org's judges, asked of every agent's calls, by name."""
+    return await _listed(gateway.connections.pool, key.org, THE_ORGS_OWN)
+
+
+@router.put("/v1/org/judges/{name}")
+async def put_org_judge(
+    name: str, body: JudgeRequest, key: EvalsKey, gateway: GatewayDep
+) -> JudgeList:
+    """Write one of the org's judges whole; the org's list after it."""
+    return await _written(gateway.connections.pool, key, THE_ORGS_OWN, name, body)
+
+
+@router.delete("/v1/org/judges/{name}")
+async def drop_org_judge(name: str, key: EvalsKey, gateway: GatewayDep) -> JudgeList:
+    """Forget one of the org's judges; the org's list after it, 404 for a name nobody wrote."""
+    return await _dropped(gateway.connections.pool, key.org, THE_ORGS_OWN, name)
+
+
+@router.get("/v1/agents/{slug}/judges")
+async def list_judges(slug: str, key: EvalsKey, gateway: GatewayDep) -> JudgeList:
+    """The agent's own judges, by name; the org's are at /v1/org/judges."""
+    return await _listed(gateway.connections.pool, key.org, slug)
+
+
+@router.put("/v1/agents/{slug}/judges/{name}")
+async def put_judge(
+    slug: str, name: str, body: JudgeRequest, key: EvalsKey, gateway: GatewayDep
+) -> JudgeList:
+    """Write one of the agent's own judges whole; the agent's list after it."""
+    return await _written(gateway.connections.pool, key, slug, name, body)
+
+
+@router.delete("/v1/agents/{slug}/judges/{name}")
+async def drop_judge(slug: str, name: str, key: EvalsKey, gateway: GatewayDep) -> JudgeList:
+    """Forget one of the agent's own judges; its list after it, 404 for a name nobody wrote."""
+    return await _dropped(gateway.connections.pool, key.org, slug, name)
+
+
+async def _written(pool: Pool, key: Acting, agent: str, name: str, body: JudgeRequest) -> JudgeList:
+    if not A_NAME.match(name):
+        raise DeclarationRefused(NOT_A_NAME.format(name=name))
+    written = AgentJudge(name=name, question=body.question, runs_on=body.runs_on)
+    bearer = key.bearer.key
+    await judges.put_judge(pool, key.org, agent, written, author=bearer.subject or bearer.key_id)
+    return await _listed(pool, key.org, agent)
+
+
+async def _dropped(pool: Pool, org: str, agent: str, name: str) -> JudgeList:
+    await judges.drop_judge(pool, org, agent, name)
+    return await _listed(pool, org, agent)
+
+
+async def _listed(pool: Pool, org: str, agent: str) -> JudgeList:
+    return JudgeList(
+        judges=[_row_of(stored) for stored in await judges.judges_of(pool, org, agent)]
+    )
+
+
+def _row_of(stored: StoredJudge) -> JudgeRow:
+    judge = stored.judge
+    return JudgeRow(
+        name=judge.name,
+        question=judge.question,
+        runs_on=judge.runs_on,
+        author=stored.author,
+        set_at=stored.set_at.timestamp(),
+    )

pinecall/gateway/api/keys.py

@@ -0,0 +1,110 @@
+"""The org's keys: listed by fingerprint, a server's token minted, one revoked."""
+
+from datetime import UTC, datetime
+
+from fastapi import APIRouter
+
+from pinecall.domain.errors import NotAllowed, NotFound
+from pinecall.domain.names import PRODUCTION, parse_env
+from pinecall.domain.person import THE_KEYS
+from pinecall.gateway._deps import AppKey, BearerDep, GatewayDep
+from pinecall.tenancy import keys, people
+from pinecall.tenancy.keys import Bearer, ListedKey
+from pinecall.wire.rest.accounts import (
+    CreateKeyRequest,
+    KeyIssuedResponse,
+    KeyRow,
+    RevokeKeyResponse,
+)
+
+router = APIRouter()
+
+
+# Made by a person and owned by the org, so it outlives whoever made it.
+BY_A_PERSON = "a server's token is made by a person, from Tokens in the console"
+
+
+NO_PRODUCTION = "{name} has no production access: a production token is made by somebody who has"
+
+
+# One sentence for another org's key, a revoked one and one that is not yours to stop.
+NO_SUCH_KEY = "no live key of this org has the fingerprint {fingerprint}"
+
+
+# Any key: every server's token, and the asker's own person keys, or every person's with `keys`.
+@router.get("/v1/keys")
+async def list_keys(key: BearerDep, gateway: GatewayDep) -> list[KeyRow]:
+    """The org's keys this key may see, oldest first, the revoked ones too; never a key."""
+    pool = gateway.connections.pool
+    names = {member.id: member.name for member in await people.listed(pool, key.key.org)}
+    return [
+        key_row(row, names)
+        for row in await keys.listed(pool, key.key.org)
+        if row.key.subject is None
+        or row.key.subject == key.key.subject
+        or THE_KEYS in key.key.scopes
+    ]
+
+
+# Only the fingerprint is kept: the token is in this answer and never again.
+@router.post("/v1/keys")
+async def create_key(body: CreateKeyRequest, key: AppKey, gateway: GatewayDep) -> KeyIssuedResponse:
+    """A server's token for the org in one world, `pc_live_` or `pc_test_`."""
+    env = parse_env(body.env)
+    person = key.bearer.member
+    if key.bearer.key.subject is None or person is None:
+        raise NotAllowed(BY_A_PERSON)
+    if env == PRODUCTION and not person.opens_production:
+        raise NotAllowed(NO_PRODUCTION.format(name=person.name))
+    keys.check_expiry(body.expires_at, datetime.now(UTC))
+    issued = keys.Issued(
+        org=key.org,
+        env=env,
+        scopes=keys.server_scopes(body.scopes),
+        label=body.label,
+        created_by=person.id,
+        expires_at=body.expires_at,
+    )
+    minted, secret = await keys.issue(gateway.connections.pool, issued)
+    return KeyIssuedResponse.of(minted, secret)
+
+
+# A POST, not a DELETE: the row stays, so the entries that name the key still read.
+@router.post("/v1/keys/{fingerprint}/revoke")
+async def revoke_key(fingerprint: str, key: BearerDep, gateway: GatewayDep) -> RevokeKeyResponse:
+    """Stop one of the org's keys from the next request on: your own, one you made, or any."""
+    pool = gateway.connections.pool
+    listed = await keys.listed(pool, key.key.org)
+    row = next((row for row in listed if row.fingerprint == fingerprint), None)
+    if row is None or row.revoked_at is not None or not _may_stop(key, row):
+        raise NotFound(NO_SUCH_KEY.format(fingerprint=fingerprint))
+    stopped = await keys.revoke(pool, fingerprint)
+    if not stopped:
+        raise NotFound(NO_SUCH_KEY.format(fingerprint=fingerprint))
+    for each in stopped:
+        gateway.keys.forget(fingerprint=each)
+    return RevokeKeyResponse(fingerprint=fingerprint, revoked=True)
+
+
+def key_row(row: ListedKey, names: dict[str, str]) -> KeyRow:
+    """A listed key as the doors send it, its maker named where the org still knows them."""
+    is_a_persons = row.key.subject is not None
+    return KeyRow(
+        fingerprint=row.fingerprint,
+        label=row.key.label,
+        kind="person" if is_a_persons else "server",
+        env=None if is_a_persons else row.key.env,
+        name=row.key.name,
+        created_by=None if row.created_by is None else names.get(row.created_by, row.created_by),
+        created_at=row.created_at,
+        last_used_at=row.last_used_at,
+        revoked_at=row.revoked_at,
+        scopes=sorted(row.key.scopes),
+        expires_at=row.key.expires_at,
+    )
+
+
+def _may_stop(key: Bearer, row: ListedKey) -> bool:
+    subject = key.key.subject
+    mine = subject is not None and subject in (row.key.subject, row.created_by)
+    return mine or THE_KEYS in key.key.scopes

pinecall/gateway/api/line.py

@@ -0,0 +1,142 @@
+"""The developer's line: whose terminal a ring at the agent lands in, and their phones."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+
+from pinecall.channels import routes
+from pinecall.channels.telephony import sip
+from pinecall.domain.errors import (
+    Conflict,
+    NotAllowed,
+)
+from pinecall.domain.names import SANDBOX, parse_e164
+from pinecall.domain.scope import Scope
+from pinecall.fleet import worlds
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import Acting, AppKey, CallsKey, FleetKey, GatewayDep, ScopeDep
+from pinecall.gateway._gateway import Gateway
+from pinecall.wire.rest.agents import (
+    DeveloperPhones,
+    RingHandoff,
+    RingTarget,
+    ScopeHolder,
+    TestNumber,
+    TestNumbers,
+)
+
+router = APIRouter()
+
+
+NOT_IN_PRODUCTION = "production has one corner and the org holds it: there is nothing to route"
+
+NOBODY_TO_ROUTE_TO = "a phone reaches a person's own corner, and this key names no person"
+
+
+@router.get("/v1/agents/{slug}/line")
+async def get_line(slug: str, _key: CallsKey, where: ScopeDep, gateway: GatewayDep) -> RingTarget:
+    """Who holds the agent's line, and who else could take it."""
+    return await _line(gateway, where, slug)
+
+
+@router.post("/v1/agents/{slug}/line")
+async def take_line(slug: str, _key: AppKey, where: ScopeDep, gateway: GatewayDep) -> RingTarget:
+    """Take the agent's line for this scope."""
+    gateway.sockets.take_the_line(where, slug)
+    return await _line(gateway, where, slug)
+
+
+@router.delete("/v1/agents/{slug}/line")
+async def drop_line(slug: str, _key: AppKey, where: ScopeDep, gateway: GatewayDep) -> RingTarget:
+    """Let the line go, to the newest other scope that could take it."""
+    gateway.sockets.drop_the_line(where, slug)
+    return await _line(gateway, where, slug)
+
+
+@router.put("/v1/line/from")
+async def put_developer_phones(
+    developer_phones: DeveloperPhones, key: AppKey, gateway: GatewayDep
+) -> dict[str, list[str]]:
+    """Send rings from this phone to the key's person's own scope."""
+    holder = _person_of(key)
+    gateway.sockets.calls_from(key.env, parse_e164(developer_phones.number), holder)
+    return {"calling": gateway.sockets.calling(key.env, holder)}
+
+
+@router.delete("/v1/line/from")
+async def drop_developer_phones(key: AppKey, gateway: GatewayDep) -> dict[str, list[str]]:
+    """Stop sending this person's phones to their scope, and say which were forgotten."""
+    return {"forgot": gateway.sockets.forget_calls_from(key.env, _person_of(key))}
+
+
+# A developer lacks the numbers scope in production: this shows production's numbers and agents.
+@router.get("/v1/line/numbers")
+async def list_test_numbers(key: AppKey, gateway: GatewayDep) -> TestNumbers:
+    """The production numbers a developer's phone can dial, and the phones that are theirs."""
+    holder = _person_of(key)
+    doors = await routes.of_org(gateway.connections.pool, key.org, "production")
+    return TestNumbers(
+        calling=gateway.sockets.calling(key.env, holder),
+        numbers=[
+            TestNumber(number=door.number, agent=door.agent)
+            for door in doors
+            if door.channel == "phone" and door.number is not None
+        ],
+    )
+
+
+# A developer's own phone dialling the production number reaches their sandbox copy, while they
+# hold it; every other caller reaches production. Where the sandbox has a LiveKit of its own, the
+# ring is dialled there over SIP, through the trunk the answer carries.
+@router.get("/v1/agents/{slug}/rings-for")
+async def rings_for(
+    slug: str,
+    _key: FleetKey,
+    gateway: GatewayDep,
+    org: Annotated[str, Query()],
+    caller: Annotated[str, Query()],
+) -> RingHandoff:
+    """Where a production ring from this phone goes: a developer's scope and fleet, or nowhere."""
+    taking = gateway.sockets.taking(Scope(org, SANDBOX), slug, caller)
+    if taking is None or not taking.scope.holder:
+        return RingHandoff()
+    if caller not in gateway.sockets.calling(SANDBOX, taking.scope.holder):
+        return RingHandoff()
+    fleet = worlds.fleet_of(await worlds.fleets(gateway.connections.pool), SANDBOX)
+    trunk = sip.hand_over_trunk(gateway.connections, caller)
+    return RingHandoff(holder=taking.scope.holder, fleet=fleet, trunk=trunk)
+
+
+def _person_of(key: Acting) -> str:
+    if key.env != SANDBOX:
+        raise Conflict(NOT_IN_PRODUCTION)
+    if key.bearer.member is None:
+        raise NotAllowed(NOBODY_TO_ROUTE_TO)
+    return key.bearer.member.id
+
+
+async def _line(gateway: Gateway, where: Scope, slug: str) -> RingTarget:
+    holder = gateway.sockets.line_of(where.env, slug)
+    waiting = [
+        item
+        for item in gateway.sockets.waiting_for_the_line(where, slug)
+        if item.scope.holder != holder
+    ]
+    holding = None
+    if holder is not None:
+        holding = await _deps.named_holder(
+            gateway, Scope(where.org, where.env, holder)
+        ) or ScopeHolder(holder=None, name=None)
+    return RingTarget(
+        agent=slug,
+        env=where.env,
+        held=holder is not None,
+        holding=holding,
+        # In production every holder is the org's own: the line is never "yours" there.
+        yours=holder is not None and holder == where.holder and where.env == SANDBOX,
+        waiting=[
+            await _deps.named_holder(gateway, waiter.scope) or ScopeHolder(holder=None, name=None)
+            for waiter in waiting
+        ],
+        calling=gateway.sockets.calling(where.env, where.holder) if where.holder else [],
+    )