pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/gateway/_text_calls.py

@@ -0,0 +1,182 @@
+"""Written calls on the gateway: opened on the socket that holds the agent, or taken up again."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass, replace
+from datetime import UTC, date, datetime
+
+from pinecall.domain.agent import AgentConfig, Versions
+from pinecall.domain.call import CallContext, Route, today_in
+from pinecall.domain.errors import Conflict
+from pinecall.domain.names import CHANNELS_WITH_A_NUMBER, JsonObject
+from pinecall.domain.scope import Scope
+from pinecall.evals import goldens
+from pinecall.gateway._call_setup import keys_of, tuned
+from pinecall.gateway._served import Served, Serving
+from pinecall.gateway._sockets import Registration
+from pinecall.gateway.calls.binding import attach
+from pinecall.gateway.calls.serving import looked_up, served_call
+from pinecall.gateway.ending.seal import sealed
+from pinecall.log import openings, private, queries
+from pinecall.log.store import Claim
+from pinecall.providers import catalog
+from pinecall.providers.build import Running
+from pinecall.providers.credentials import thinking
+from pinecall.session import text
+from pinecall.session.call import Call, Platform
+from pinecall.session.session import Session
+from pinecall.session.text import text_session
+from pinecall.tenancy import admission
+from pinecall.tenancy.scopes import Picked
+from pinecall.wire.events import (
+    TERMINAL_EVENT,
+    CallStarted,
+)
+from pinecall.wire.frames import Entry
+from pinecall.wire.metrics import LLMModelUsage, ModelUsage
+from pinecall.wire.parts import PlatformTool
+from pinecall.wire.rest.calls import LookupRequest, SealCallRequest
+
+# A written call's session runs on one gateway, which says so: another takes it up only once that
+# gateway fell silent.
+RUNS_ELSEWHERE = "call {call} runs on another gateway: it is taken up there"
+
+
+@dataclass(frozen=True)
+class TextSetup:
+    """What a written call runs on: the tuned config, its versions, the model, a golden's facts."""
+
+    config: AgentConfig
+    versions: Versions
+    model: Running
+    # A golden's facts, which recall answers instead of the contact's memory; None on a real call.
+    recalled: tuple[str, ...] | None = None
+
+
+async def open_text(serving: Serving, registration: Registration, context: CallContext) -> Session:
+    """A new written call on the socket that holds the agent, admitted and unstarted."""
+    pool, scope = serving.connections.pool, registration.scope
+    configured = await catalog.providers(pool)
+    config, versions = await tuned(
+        pool, registration.config, scope, configured, Picked(call=context.call)
+    )
+    model = thinking(config, configured, await keys_of(pool, serving.connections.vault, scope))
+    return await open_text_as(serving, registration, context, TextSetup(config, versions, model))
+
+
+# Admission before the log is claimed: a refused call leaves nothing behind.
+async def open_text_as(
+    serving: Serving, registration: Registration, context: CallContext, setup: TextSetup
+) -> Session:
+    """A new written call on this setup, admitted and unstarted."""
+    pool, scope = serving.connections.pool, registration.scope
+    await admission.admit_call(
+        pool,
+        scope.org,
+        scope.env,
+        running=serving.live.running(scope.org, scope.env),
+        at=serving.logs.store.clock(),
+    )
+    await serving.logs.store.claim(
+        context.call,
+        registration.slug,
+        scope.org,
+        Claim(scope, setup.versions, opened_by="gateway"),
+    )
+    # Kept as a phone call's is: the gateway holding the app's socket serves it from this.
+    await openings.kept(pool, scope.org, context, setup.config)
+    await serving.prompts.keep(pool, scope.org, setup.config.knowledge or "")
+    served = served_call(serving, registration.owner, context, setup.config, scope)
+    serving.live.opened_by(context.call, "gateway")
+    await serving.live.commands_heard(context.call)
+    return _session(serving, served, setup.model, setup.recalled)
+
+
+# A gateway that restarted forgot the call, not the caller: no admission, no second greeting.
+async def resume_text(
+    serving: Serving, registration: Registration, call: str, zone: str
+) -> Session | None:
+    """A written call taken up again from its log; None for one that is over or not this agent's."""
+    kept = await queries.scope_of_call(serving.connections.pool, call)
+    if kept is None or kept.sealed or kept.scope is None or kept.agent != registration.slug:
+        return None
+    if serving.live.owners.text_elsewhere(call):
+        raise Conflict(RUNS_ELSEWHERE.format(call=call))
+    if kept.scope.org != registration.scope.org:
+        return None
+    # The model reads the tools' arguments as they were sent: the private ones opened.
+    entries = await private.opened_whole(serving.logs.store, serving.connections.vault, call)
+    if not entries or any(entry.type == TERMINAL_EVENT for entry in entries):
+        return None
+    configured = await catalog.providers(serving.connections.pool)
+    config, _ = await tuned(
+        serving.connections.pool, registration.config, kept.scope, configured, Picked(call=call)
+    )
+    model = thinking(
+        config,
+        configured,
+        await keys_of(serving.connections.pool, serving.connections.vault, kept.scope),
+    )
+    context = _as_it_opened(call, registration, kept.scope, entries, today_in(zone))
+    served = served_call(serving, None, context, config, kept.scope)
+    serving.live.opened_by(call, kept.opened_by)
+    await serving.live.commands_heard(call)
+    session = _session(serving, served, model, None)
+    # The session's batches go on from what the log already took from it, never from zero.
+    session.call.writing.after = await serving.logs.store.written(call)
+    await text.resume(session, text.taken_up(entries))
+    await attach(serving.live, call, registration.owner)
+    return session
+
+
+def tokens_of(usage: Iterable[ModelUsage]) -> int:
+    """The model tokens a call used so far: the llm_tokens quota counts these."""
+    return sum(
+        (used.input_tokens or 0) + (used.output_tokens or 0)
+        for used in usage
+        if isinstance(used, LLMModelUsage)
+    )
+
+
+def _session(
+    serving: Serving, served: Served, model: Running, recalled: tuple[str, ...] | None
+) -> Session:
+    async def lookup(tool: PlatformTool, arguments: JsonObject, speech: str | None) -> JsonObject:
+        request = LookupRequest(tool=tool, input=arguments, speech_id=speech)
+        return await looked_up(serving, served, request)
+
+    async def seal(usage: list[ModelUsage], outcome: str) -> None:
+        await sealed(serving, served, SealCallRequest(usage=usage, outcome=outcome))
+
+    looking = lookup if recalled is None else goldens.golden_lookup(recalled, lookup)
+    platform = Platform(
+        append_many=served.log.append_many, tool=served.tools.ran, lookup=looking, seal=seal
+    )
+    session = text_session(Call(served.context, served.config, platform), model)
+    serving.live.calls[served.call] = replace(served, session=session)
+    serving.live.owners.running(served.call, here=True)
+    return session
+
+
+def _as_it_opened(
+    call: str, registration: Registration, scope: Scope, entries: Iterable[Entry], today: date
+) -> CallContext:
+    started = next((entry for entry in entries if entry.type == "call.started"), None)
+    data = None if started is None else CallStarted.model_validate(started.data)
+    caller = "" if data is None else (data.from_ or "")
+    # A WhatsApp conversation comes back on its number; a chat at none.
+    channel = "web" if data is None else data.channel
+    number = data.to if data is not None and channel in CHANNELS_WITH_A_NUMBER else None
+    route = Route(
+        org=scope.org, agent=registration.slug, channel=channel, number=number, env=scope.env
+    )
+    if data is not None:
+        today = datetime.fromtimestamp(data.started_at, tz=UTC).date()
+    return CallContext(
+        call=call,
+        channel=channel,
+        direction="inbound",
+        caller=caller or call,
+        route=route,
+        today=today,
+        holder=scope.holder or None,
+    )

pinecall/gateway/api/accounts.py

@@ -0,0 +1,324 @@
+"""Who a key is, and how a person gets one: sign-in, codes, the org switch, a paired terminal."""
+
+from importlib.metadata import version
+
+from fastapi import APIRouter, Request, Response
+
+from pinecall.domain.errors import Conflict, DeclarationRefused, NotAllowed, NotFound, NotSignedIn
+from pinecall.domain.names import DISTRIBUTION, PRODUCTION
+from pinecall.domain.person import Member
+from pinecall.gateway._deps import (
+    ActingDep,
+    BearerDep,
+    GatewayDep,
+    check_knock,
+    client_of,
+    public_url,
+)
+from pinecall.postgres.pool import box_wide
+from pinecall.tenancy import keys, letters, mail, orgs, people, signin
+from pinecall.tenancy.signin import Asking
+from pinecall.wire.rest.accounts import (
+    AcceptInvitationRequest,
+    BrandRow,
+    EmptyResponse,
+    FirstKeyResponse,
+    ForgotPasswordRequest,
+    GatewayInfoResponse,
+    KeyCollectedResponse,
+    KeyIssuedResponse,
+    MemberRow,
+    MintCodeResponse,
+    OpenPairingRequest,
+    OrgOfPersonRow,
+    OrgsOfPersonResponse,
+    PairingApprovedResponse,
+    PairingStatusResponse,
+    SignInOrgRow,
+    SignInOrgsRequest,
+    SignInOrgsResponse,
+    SignInRequest,
+    SwitchOrgRequest,
+    WhoamiResponse,
+)
+
+router = APIRouter()
+
+
+ONE_OR_THE_OTHER = "log in with org, email and password, or with a code: one of the two"
+
+
+# One sentence for a code spent, dead or never minted.
+NO_CODE = "no code answers to that: it was used, it expired, or it never existed"
+
+
+# One sentence for a word collected, dead or never printed, so nobody probes which existed.
+NO_PAIRING = "no pairing answers to that: it was collected, it expired, or it never existed"
+
+
+ANSWERED = "that terminal is already signed in: it has a key waiting"
+
+
+NOT_A_PERSON = "an org's own key names nobody: a terminal is signed in as a person"
+
+
+NO_INVITATION = (
+    "no open invitation answers to that token: it was used, it expired, or it never existed"
+)
+
+
+# What a listed org says of a person of the box who is no member there.
+AS_THE_OPERATOR = "operator"
+
+
+FIRST_KEY = "invitation"
+
+
+@router.get("/.well-known/pinecall")
+async def gateway_info(gateway: GatewayDep) -> GatewayInfoResponse:
+    """What this gateway is and how it signs people in, before anybody holds a key."""
+    connections = gateway.connections
+    box_mail = await mail.box_mail_of(
+        connections.pool, connections.vault, gateway.outbox.environment
+    )
+    brand = await letters.brand_of(connections.pool)
+    return GatewayInfoResponse(
+        version=version(DISTRIBUTION),
+        signup=connections.settings.signup,
+        min_password=connections.settings.min_password,
+        mail=box_mail is not None,
+        brand=BrandRow(name=brand.name, logo_url=brand.logo_url, accent=brand.accent),
+        google=False,
+    )
+
+
+@router.get("/v1/whoami")
+async def whoami(key: ActingDep, gateway: GatewayDep) -> WhoamiResponse:
+    """Whose key this is, the world this request acts in, and what the key opens."""
+    minted, member = key.bearer.key, key.bearer.member
+    org = await orgs.find(gateway.connections.pool, minted.org)
+    return WhoamiResponse(
+        org=minted.org,
+        slug=None if org is None else org.slug,
+        key_id=minted.key_id,
+        label=minted.label,
+        env=key.env,
+        scopes=sorted(minted.scopes),
+        subject=minted.subject,
+        name=minted.name,
+        email=None if member is None else member.email,
+        operator=member is not None and member.operator,
+        visiting=member is not None and member.org != minted.org,
+        production=minted.env == PRODUCTION if member is None else member.opens_production,
+    )
+
+
+# The body says a password or a code; each is its own sign-in, and a body with both is refused.
+@router.post("/v1/login")
+async def sign_in(body: SignInRequest, request: Request, gateway: GatewayDep) -> KeyIssuedResponse:
+    """A key for a person and a device, from a password, or from a one-use code."""
+    pool = gateway.connections.pool
+    if body.code is not None:
+        if body.org is not None or body.email is not None or body.password is not None:
+            raise DeclarationRefused(ONE_OR_THE_OTHER)
+        signed = await signin.sign_in_with_code(
+            pool, gateway.signins.codes, body.code, device=body.device
+        )
+        if signed is None:
+            raise NotFound(NO_CODE)
+        return KeyIssuedResponse.of(signed.key, signed.secret)
+    if body.email is None or body.password is None:
+        raise DeclarationRefused(ONE_OR_THE_OTHER)
+    knock = f"{client_of(request)} {body.org or '*'}/{body.email}"
+    await check_knock(gateway, knock, signin.TOO_MANY.format(email=body.email))
+    typed = Asking(body.email, body.password, body.org, body.device)
+    signed = await signin.sign_in_with_password(pool, typed)
+    return KeyIssuedResponse.of(signed.key, signed.secret)
+
+
+# Throttled as the login is, and refused in its sentence, so a wrong password says nothing more.
+@router.post("/v1/login/orgs")
+async def sign_in_orgs(
+    body: SignInOrgsRequest, request: Request, gateway: GatewayDep
+) -> SignInOrgsResponse:
+    """The orgs an address and a password open, minting nothing."""
+    pool = gateway.connections.pool
+    knock = f"{client_of(request)} */{body.email}"
+    await check_knock(gateway, knock, signin.TOO_MANY.format(email=body.email))
+    opened = await signin.orgs_signed_into(pool, body.email, body.password)
+    if not opened:
+        raise NotSignedIn(signin.NOBODY)
+    rows: list[SignInOrgRow] = []
+    for row in opened:
+        org = await orgs.find(pool, row.org)
+        if org is not None:
+            rows.append(SignInOrgRow(org=org.id, slug=org.slug, name=org.name, role=row.role))
+    return SignInOrgsResponse(orgs=rows)
+
+
+# A person of the box also sees every org there is, to visit without taking a seat.
+@router.get("/v1/login/orgs")
+async def list_orgs_of_person(key: BearerDep, gateway: GatewayDep) -> OrgsOfPersonResponse:
+    """Every org this key's person may open, oldest first, and which one this key opens."""
+    pool = gateway.connections.pool
+    person = _person_of(key.member)
+    rows: list[OrgOfPersonRow] = []
+    # The person's other orgs are other orgs: read past the key's own (postgres/pool.py).
+    with box_wide():
+        for row in await people.orgs_of(pool, person.email):
+            if row.status == "disabled":
+                continue
+            org = await orgs.find(pool, row.org)
+            rows.append(
+                OrgOfPersonRow(
+                    org=row.org,
+                    slug=None if org is None else org.slug,
+                    name=None if org is None else org.name,
+                    role=row.role,
+                    status=row.status,
+                    here=row.org == key.key.org,
+                    member=True,
+                )
+            )
+        if not person.operator:
+            return OrgsOfPersonResponse(orgs=rows)
+        theirs = {row.org for row in rows}
+        for org in await orgs.listed(pool):
+            if org.id in theirs:
+                continue
+            rows.append(
+                OrgOfPersonRow(
+                    org=org.id,
+                    slug=org.slug,
+                    name=org.name,
+                    role=AS_THE_OPERATOR,
+                    status="active",
+                    here=org.id == key.key.org,
+                    member=False,
+                )
+            )
+    return OrgsOfPersonResponse(orgs=rows)
+
+
+@router.post("/v1/login/org")
+async def switch_org(
+    body: SwitchOrgRequest, key: BearerDep, gateway: GatewayDep
+) -> KeyIssuedResponse:
+    """The same person's key in another org of theirs, or a visit for a person of the box."""
+    pool = gateway.connections.pool
+    person = _person_of(key.member)
+    # The org asked for is another org, and the key minted is written in it.
+    with box_wide():
+        org = await orgs.find(pool, body.org)
+        if org is None:
+            raise NotAllowed(signin.NOT_THEIRS.format(org=body.org))
+        signed = await signin.key_in(pool, person, org.id, label=key.key.label)
+    return KeyIssuedResponse.of(signed.key, signed.secret)
+
+
+# A browser signs in with the code, so a key never rides a URL.
+@router.post("/v1/login/codes")
+async def mint_code(key: BearerDep, gateway: GatewayDep) -> MintCodeResponse:
+    """A one-use word that gives a browser a key like this one, for five minutes."""
+    code, expires_at = await gateway.signins.codes.mint(key.key)
+    return MintCodeResponse(code=code, expires_at=expires_at)
+
+
+# 202 whoever asks, and throttled like the login, so the door says nothing about who exists.
+@router.post("/v1/login/reset", status_code=202)
+async def forget_password(
+    body: ForgotPasswordRequest, request: Request, gateway: GatewayDep
+) -> EmptyResponse:
+    """Mail a one-use link that sets the password, where one can go."""
+    knock = f"{client_of(request)} */{body.email}"
+    await check_knock(gateway, knock, signin.TOO_MANY.format(email=body.email))
+    await signin.forgotten(
+        gateway.connections.pool, gateway.outbox, body.email, public_url(request, gateway)
+    )
+    return EmptyResponse()
+
+
+@router.post("/v1/login/pairings")
+async def open_pairing(body: OpenPairingRequest, gateway: GatewayDep) -> MintCodeResponse:
+    """The word a terminal prints for a browser to approve, and when it dies."""
+    code, expires_at = await gateway.signins.pairings.open(body.device)
+    return MintCodeResponse(code=code, expires_at=expires_at)
+
+
+# Reading it does not spend it, so the approving page can be reloaded.
+@router.get("/v1/login/pairings/{code}")
+async def pairing_status(code: str, gateway: GatewayDep) -> PairingStatusResponse:
+    """Which terminal a browser is about to sign in, and whether it is answered."""
+    waiting = await gateway.signins.pairings.asking(code)
+    if waiting is None:
+        raise NotFound(NO_PAIRING)
+    return PairingStatusResponse(
+        device=waiting.device, expires_at=waiting.expires_at, answered=waiting.answered
+    )
+
+
+# The password is typed in the browser, never the terminal, so this works with SSO too; the
+# terminal gets a key of its own, never the browser's.
+@router.post("/v1/login/pairings/{code}")
+async def approve_pairing(
+    code: str, key: BearerDep, gateway: GatewayDep
+) -> PairingApprovedResponse:
+    """Sign the terminal in as the person this browser is."""
+    if key.key.subject is None or key.member is None:
+        raise NotAllowed(NOT_A_PERSON)
+    pairings = gateway.signins.pairings
+    waiting = await pairings.asking(code)
+    if waiting is None:
+        raise NotFound(NO_PAIRING)
+    if waiting.answered:
+        raise Conflict(ANSWERED)
+    signed = await signin.another_key(
+        gateway.connections.pool, key.key, key.member, device=waiting.device
+    )
+    if not await pairings.fill(code, signed.secret, signed.key.org):
+        raise Conflict(ANSWERED)
+    org = await orgs.find(gateway.connections.pool, signed.key.org)
+    return PairingApprovedResponse(
+        device=waiting.device,
+        org=signed.key.org,
+        org_name=signed.key.org if org is None else org.name,
+    )
+
+
+# 202 is "ask again"; 404 is a word gone, and an empty 200 would read as a key of "".
+@router.get("/v1/login/pairings/{code}/key")
+async def collect_key(
+    code: str, response: Response, gateway: GatewayDep
+) -> KeyCollectedResponse | EmptyResponse:
+    """The terminal's key, once; 202 while nobody has approved."""
+    collected = await gateway.signins.pairings.collect(code)
+    if collected.key is not None:
+        return KeyCollectedResponse(key=collected.key)
+    if not collected.waiting:
+        raise NotFound(NO_PAIRING)
+    response.status_code = 202
+    return EmptyResponse()
+
+
+# No key: the week-long, one-use token is the credential. An invitation seats the person with the
+# password they have, or their first one; a reset link sets it again.
+@router.post("/v1/invitations/{token}")
+async def accept_invitation(
+    token: str, body: AcceptInvitationRequest, gateway: GatewayDep
+) -> FirstKeyResponse:
+    """Type the password: the member is active, and here is their first key."""
+    pool = gateway.connections.pool
+    shortest = gateway.connections.settings.min_password
+    people.check_password(body.password, shortest)
+    member = await people.accept(pool, token, body.password, shortest)
+    if member is None:
+        raise NotFound(NO_INVITATION)
+    minted, secret = await keys.person_key(pool, member, label=body.device or FIRST_KEY)
+    issued = KeyIssuedResponse.of(minted, secret)
+    return FirstKeyResponse(**issued.model_dump(), member=MemberRow.of(member))
+
+
+def _person_of(member: Member | None) -> Member:
+    if member is None:
+        raise NotAllowed(signin.NOT_A_PERSONS)
+    return member

pinecall/gateway/api/agents.py

@@ -0,0 +1,150 @@
+"""What a worker asks about an agent, and the agents and routes the org holds."""
+
+import dataclasses
+import time
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Response
+from pydantic import BaseModel
+
+from pinecall.channels import routes
+from pinecall.domain.agent import AgentConfig
+from pinecall.domain.call import Route
+from pinecall.domain.errors import (
+    NotFound,
+)
+from pinecall.domain.names import THE_WIDGET, Channel
+from pinecall.domain.person import THE_FLEET
+from pinecall.domain.scope import Scope
+from pinecall.gateway import _deps
+from pinecall.gateway._call_setup import keys_of, tuned
+from pinecall.gateway._deps import CallsKey, DispatchedDep, GatewayDep, ScopeDep, WorkerKey
+from pinecall.gateway._gateway import Gateway
+from pinecall.gateway._sockets import NO_AGENT, Registration
+from pinecall.providers import catalog
+from pinecall.providers.credentials import Pipeline, pipeline
+from pinecall.tenancy import agents, keys
+from pinecall.tenancy.scopes import Picked
+from pinecall.wire.rest.agents import (
+    AgentList,
+    AgentRow,
+    HoldAudio,
+)
+
+router = APIRouter()
+
+
+# Every agent answers on the widget; no route row is needed for it.
+ON_THE_WEB: frozenset[Channel] = frozenset({THE_WIDGET})
+
+
+class RouteQuery(BaseModel):
+    """A worker asking for the route a number rings, across every org."""
+
+    number: str | None = None
+    channel: Channel = "phone"
+
+
+# A worker names the call it asks for before opening it (`for_call`: `call` would ask to act in an
+# opened call's scope), so a canary's share is picked by the call's id; a worker that names none
+# (an older one) is answered the version every call off the canary runs.
+@router.get("/v1/agents/{slug}/config")
+async def agent_config(
+    slug: str,
+    _key: _deps.DeclarationKey,
+    where: ScopeDep,
+    gateway: GatewayDep,
+    for_call: Annotated[str | None, Query()] = None,
+) -> AgentConfig:
+    """The agent as the scope runs it, for the call named: its declaration under the settings."""
+    found = _registration_of(gateway, where, slug)
+    configured = await catalog.providers(gateway.connections.pool)
+    tuned_config, _ = await tuned(
+        gateway.connections.pool, found.config, where, configured, Picked(call=for_call)
+    )
+    return tuned_config
+
+
+# The one answer that carries keys: to the fleet's key, or the org's own worker's. The box's
+# keys leave it only for its own workers: an org's process is handed the org's keys alone.
+@router.get("/v1/agents/{slug}/provider-keys")
+async def agent_credentials(
+    slug: str,
+    key: WorkerKey,
+    where: ScopeDep,
+    gateway: GatewayDep,
+    for_call: Annotated[str | None, Query()] = None,
+) -> Pipeline:
+    """The three stages a call of the agent runs, each on the key it runs on."""
+    found = _registration_of(gateway, where, slug)
+    configured = await catalog.providers(gateway.connections.pool)
+    tuned_config, _ = await tuned(
+        gateway.connections.pool, found.config, where, configured, Picked(call=for_call)
+    )
+    keys = await keys_of(gateway.connections.pool, gateway.connections.vault, where)
+    if THE_FLEET not in key.bearer.key.scopes:
+        keys = dataclasses.replace(keys, lends=frozenset())
+    now = time.monotonic()
+    stages = pipeline(tuned_config, configured, keys).demoting(gateway.counters.failing(now))
+    gateway.counters.handed_out((stages.llm.vendor, stages.stt.vendor, stages.tts.vendor), now)
+    return stages
+
+
+@router.get("/v1/agents/{slug}/hold-audio")
+async def hold_audio(slug: str, _key: WorkerKey, where: ScopeDep, gateway: GatewayDep) -> HoldAudio:
+    """What a caller of the agent hears while a tool runs."""
+    chosen = await agents.hold_of(gateway.connections.pool, where, slug)
+    if chosen is None:
+        return HoldAudio(played="default")
+    return HoldAudio(
+        played=chosen.played, sha256=chosen.sha256, seconds=chosen.seconds, name=chosen.name
+    )
+
+
+@router.get("/v1/agents/{slug}/hold-audio/audio")
+async def hold_clip(slug: str, _key: WorkerKey, where: ScopeDep, gateway: GatewayDep) -> Response:
+    """The org's own clip, Ogg Opus."""
+    audio = await agents.hold_audio(gateway.connections.pool, where, slug)
+    if audio is None:
+        raise NotFound(f"agent {slug} plays no clip of its own")
+    return Response(audio, media_type="audio/ogg")
+
+
+# A route the operator adds answers the next job: nothing is cached.
+@router.get("/v1/routes")
+async def list_routes(
+    key: WorkerKey,
+    named: DispatchedDep,
+    gateway: GatewayDep,
+    query: Annotated[RouteQuery, Query()],
+) -> list[Route]:
+    """The routes of a scope; for the fleet's key and a number, the route that number rings."""
+    fleet = THE_FLEET in key.bearer.key.scopes
+    if fleet and query.number is not None:
+        found = await routes.at(gateway.connections.pool, query.channel, query.number)
+        return [] if found is None or found.env != key.bearer.key.env else [found]
+    where = named if fleet and named is not None else keys.scope_of(key.bearer, key.env)
+    return await routes.of_org(gateway.connections.pool, where.org, where.env)
+
+
+@router.get("/v1/agents")
+async def list_agents(key: CallsKey, where: ScopeDep, gateway: GatewayDep) -> AgentList:
+    """The org's held agents in the world: one row per slug, one per scope for a team reader."""
+    every = _deps.sees_every_scope(key)
+    doors: dict[str, set[Channel]] = {}
+    for route in await routes.of_org(gateway.connections.pool, where.org, where.env):
+        doors.setdefault(route.agent, set()).add(route.channel)
+    listed: list[AgentRow] = []
+    for registration in gateway.sockets.holding(where, every_corner=every):
+        channels = sorted(doors.get(registration.slug, set[Channel]()) | ON_THE_WEB)
+        holder = await _deps.named_holder(gateway, registration.scope)
+        listed.append(AgentRow(slug=registration.slug, channels=channels, holder=holder))
+    return AgentList(agents=listed)
+
+
+# Another org's agent is the same 404 as nobody's: its existence does not leak.
+def _registration_of(gateway: Gateway, where: Scope, slug: str) -> Registration:
+    registration = gateway.sockets.of(where, slug)
+    if registration is None or registration.scope.org != where.org:
+        raise NotFound(NO_AGENT.format(slug=slug))
+    return registration