pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/session/voice.py

@@ -0,0 +1,118 @@
+"""A session opened for a spoken call: the pipeline, the turn options, the ears' keyterms."""
+
+from collections.abc import Sequence
+from functools import cache
+
+from livekit.agents import (
+    NOT_GIVEN,
+    NotGivenOr,
+    inference,
+)
+from livekit.agents.voice import AgentSession, STTContextOptions
+from livekit.agents.voice import text_transforms as transforms
+from livekit.agents.voice.agent_session import DEFAULT_TTS_TEXT_TRANSFORMS
+from livekit.agents.voice.turn import InterruptionOptions, TurnDetectionMode, TurnHandlingOptions
+from smart_turn_livekit import SmartTurnDetector  # pyright: ignore[reportMissingTypeStubs]
+
+from pinecall.domain.agent import AgentConfig
+from pinecall.providers.build import (
+    Ears,
+    Running,
+    TurnModel,
+    ears_of,
+    speaking_of,
+    thinking_of,
+)
+from pinecall.providers.credentials import Pipeline
+from pinecall.session import tools
+from pinecall.session._hearing import keyterms, policy_for
+from pinecall.session._livekit import switches_written
+from pinecall.session.call import Call
+from pinecall.session.session import ONE_ANSWER_PER_TOOL, Session
+from pinecall.session.tools import VOICE_LOOKUP_MS
+
+# The local end-of-turn model: left unset, livekit may pick the hosted one and send the
+# caller's words to a cloud.
+LOCAL_TURN_VERSION: inference.TurnDetectorVersions = "v1-mini"
+
+# The checkpoint in smart-turn-livekit's registry: upstream's, benchmarked on 23 languages.
+SMART_TURN: TurnModel = "smart-turn-v3"
+
+
+def voice_session(call: Call, stages: Pipeline) -> Session:
+    """A voice call: the three stages built for it, the turn taken as a phone line needs."""
+    thinking, ears, voice = (
+        thinking_of(stages.llm),
+        ears_of(stages.stt, call.config.turn),
+        speaking_of(stages.tts),
+    )
+    switches_written(call.writing, (thinking, ears, voice))
+    live: AgentSession[None] = AgentSession(
+        llm=thinking,
+        stt=ears,
+        tts=voice,
+        turn_handling=_spoken_turns(call.config, stages.stt),
+        # Word timings reach transcription_node only from an aligned voice.
+        use_tts_aligned_transcript=True,
+        tts_text_transforms=_text_transforms_of(call.config),
+        stt_context_options=context_of(call.config, ears),
+        max_tool_steps=ONE_ANSWER_PER_TOOL,
+    )
+    return Session(
+        live, (thinking, ears, voice), tools.Lookups(call, call.platform.lookup, VOICE_LOOKUP_MS)
+    )
+
+
+def context_of(config: AgentConfig, ears: Ears) -> NotGivenOr[STTContextOptions]:
+    """The keyterms the ears are told at start, when they take any."""
+    if not config.hears or not ears.capabilities.keyterms:
+        return NOT_GIVEN
+    return {"keyterms": keyterms(config, {})}
+
+
+# One Smart Turn per process: its weights load once and its first inference runs when it is made,
+# so only the first call that asks for it pays. Each session streams to it on its own.
+@cache
+def smart_turn() -> SmartTurnDetector:
+    """Smart Turn v3, the row's alternative to livekit's own detector."""
+    return SmartTurnDetector(SMART_TURN)
+
+
+def _end_of_turn(model: TurnModel) -> TurnDetectionMode:
+    """The local model that reads the end of the caller's turn off the audio, no transcript."""
+    if model == SMART_TURN:
+        return smart_turn()
+    return inference.TurnDetector(version=LOCAL_TURN_VERSION)
+
+
+# The parameter replaces livekit's defaults, so they come first and the tenant's words after.
+def _text_transforms_of(config: AgentConfig) -> NotGivenOr[Sequence[transforms.TextTransforms]]:
+    """Livekit's own transforms, then the tenant's pronunciations."""
+    if not config.says:
+        return NOT_GIVEN
+    return [*DEFAULT_TTS_TEXT_TRANSFORMS, transforms.replace(dict(config.says))]
+
+
+# Interruptions are judged by the local VAD: livekit's adaptive detector streams the caller's
+# audio to its cloud. A false interruption is not resumed: livekit replays the whole sentence.
+# No endpointing here: the agent's own already reaches the ears, and both would wait twice.
+def _spoken_turns(config: AgentConfig, ears: Running) -> TurnHandlingOptions:
+    r"""How the caller takes the floor, from the agent\'s language and its own turn knobs."""
+    policy = policy_for(config.language, config.turn)
+    interruption: InterruptionOptions = {
+        "min_words": policy.min_words,
+        "mode": "vad",
+        "false_interruption_timeout": policy.false_interruption_s,
+        "resume_false_interruption": False,
+    }
+    if policy.min_speech_s is not None:
+        interruption["min_duration"] = policy.min_speech_s
+    return {
+        # Ears that end the turn themselves decide it; the local detector stacked on them waits
+        # its whole delay after a pause in the middle of a sentence.
+        "turn_detection": "stt" if ears.ends_the_turn else _end_of_turn(ears.turn_model),
+        # A reply started inside a tool's window, on a context without its result, answers its
+        # own question.
+        "preemptive_generation": {"enabled": False},
+        "interruption": interruption,
+    }

pinecall/session/widget.py

@@ -0,0 +1,201 @@
+"""The DataChannel to a browser widget: the public log of its call, and the events it sends."""
+
+import asyncio
+import json
+import logging
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine
+from dataclasses import dataclass
+
+from livekit import rtc
+from pydantic import TypeAdapter, ValidationError
+
+from pinecall.domain.errors import PinecallError
+from pinecall.domain.names import JsonObject
+from pinecall.domain.person import READS_ITS_OWN_CALL
+from pinecall.domain.scope import SCOPE_ATTRIBUTE
+from pinecall.log.readers import project_entry, project_state
+from pinecall.session.call import Call
+from pinecall.wire.events import EventReceived
+from pinecall.wire.frames import Entry
+from pinecall.wire.state import State
+
+logger = logging.getLogger(__name__)
+
+# The topics of docs/protocol/projections.md; pinecall.ui is room.send's.
+LOG = "pinecall.log"
+SNAPSHOT = "pinecall.snapshot"
+REPLAY = "pinecall.replay"
+EVENT = "pinecall.event"
+_A_JSON_OBJECT: TypeAdapter[JsonObject] = TypeAdapter(JsonObject)
+
+# What a widget's greeting waits for the log to hold its arrival.
+FLUSH_S = 5.0
+
+
+# Only the gateway numbers a log's entries, so what reaches a browser is read back from it,
+# never taken from what the session wrote.
+@dataclass(frozen=True)
+class Reading:
+    """The call's log as the gateway holds it: the state now, a stretch of it, and its tail."""
+
+    state: Callable[[], Awaitable[tuple[State, int]]]
+    since: Callable[[int], AsyncIterator[Entry]]
+    tail: Callable[[int], AsyncIterator[Entry]]
+
+
+class Widget:
+    """One call's channel to its widgets: one tail of the log, projected for each of them."""
+
+    def __init__(self, call: Call, room: rtc.Room, reading: Reading) -> None:
+        """A channel nobody listens to yet."""
+        self.call = call
+        self.room = room
+        self.reading = reading
+        # What each widget in the room has been sent, by its seat.
+        self.audience: dict[str, int] = {}
+        self.cursor = 0
+        self.tailing: asyncio.Task[None] | None = None
+        self.answering: set[asyncio.Task[None]] = set()
+
+    def watch(self) -> None:
+        """Greet each widget that is or comes into the room, and hear what it sends."""
+        for name, listener in self._listeners().items():
+            self.room.on(name, listener)  # pyright: ignore[reportUnknownMemberType]
+
+    def stop(self) -> None:
+        """Let go of the room and of the tail."""
+        for name, listener in self._listeners().items():
+            self.room.off(name, listener)  # pyright: ignore[reportUnknownMemberType]
+        for task in (self.tailing, *self.answering):
+            if task is not None:
+                task.cancel()
+        self.tailing = None
+        self.answering.clear()
+
+    def _listeners(self) -> dict[rtc.room.EventTypes, Callable[..., None]]:
+        return {
+            "connection_state_changed": self._connection,
+            "participant_connected": self._arrived,
+            "participant_disconnected": self._left,
+            "data_received": self._received,
+        }
+
+    def _connection(self, state: int) -> None:
+        if state == rtc.ConnectionState.CONN_CONNECTED:
+            for seat in self.room.remote_participants.values():
+                self._arrived(seat)
+
+    def _arrived(self, seat: rtc.RemoteParticipant) -> None:
+        if _a_widget(seat):
+            self._answer(self._greet(seat.identity))
+
+    def _left(self, seat: rtc.RemoteParticipant) -> None:
+        self.audience.pop(seat.identity, None)
+
+    # Flushed first, so the snapshot holds the widget's own arrival. What the tail sent past the
+    # snapshot is sent again to this widget alone: nothing skipped, nothing twice.
+    async def _greet(self, identity: str) -> None:
+        await self.call.writing.flushed(FLUSH_S)
+        state, last = await self.reading.state()
+        public = project_state(state, "public", self.call.config, identity)
+        await self._publish(SNAPSHOT, {"state": public, "last_seq": last}, identity)
+        if self.tailing is None:
+            self.cursor = last
+            self.tailing = asyncio.create_task(self._tail(last))
+        sent = last
+        while sent < self.cursor:
+            sent = await self._resend(identity, sent, self.cursor)
+        self.audience[identity] = sent
+
+    async def _tail(self, after: int) -> None:
+        async for entry in self.reading.tail(after):
+            self.cursor = entry.seq
+            for identity, sent in sorted(self.audience.items()):
+                if entry.seq > sent:
+                    await self._send(entry, identity)
+                # A widget that left while this was sent is not added back.
+                if identity in self.audience:
+                    self.audience[identity] = max(sent, entry.seq)
+
+    async def _resend(self, identity: str, after: int, until: int) -> int:
+        sent = after
+        async for entry in self.reading.since(after):
+            if entry.seq > until:
+                break
+            sent = entry.seq
+            await self._send(entry, identity)
+        return max(sent, until)
+
+    async def _send(self, entry: Entry, identity: str) -> None:
+        public = project_entry(entry, "public", self.call.config, identity)
+        if public is not None:
+            await self._publish(LOG, public, identity)
+
+    async def _publish(self, topic: str, payload: JsonObject, identity: str) -> None:
+        packed = json.dumps(payload, separators=(",", ":")).encode()
+        await self.room.local_participant.publish_data(
+            packed, topic=topic, destination_identities=[identity]
+        )
+
+    # Only a widget's seat speaks here. A replay ends with log.caught_up, as the SSE door's does;
+    # an event must be one the agent declared a participant may send.
+    def _received(self, packet: rtc.DataPacket) -> None:
+        sender = packet.participant
+        if sender is None or not _a_widget(sender):
+            return
+        data = _decoded(packet.data)
+        if packet.topic == REPLAY and isinstance(data.get("after"), int):
+            after = data["after"]
+            if isinstance(after, int):
+                self._answer(self._replay(sender.identity, after))
+        elif packet.topic == EVENT:
+            self._event(sender.identity, data)
+
+    async def _replay(self, identity: str, after: int) -> None:
+        sent = await self._resend(identity, after, self.cursor)
+        caught_up = Entry(
+            seq=sent,
+            ts=time.time(),
+            call=self.call.context.call,
+            agent=self.call.config.slug,
+            type="log.caught_up",
+            ephemeral=True,
+            data={"seq": sent},
+        )
+        await self._send(caught_up, identity)
+
+    def _event(self, identity: str, payload: JsonObject) -> None:
+        name, data = payload.get("name"), payload.get("data")
+        if not isinstance(name, str) or not isinstance(data, dict):
+            logger.warning("%s from a widget is not {name, data}; dropped", EVENT)
+            return
+        if not self.call.config.accepts(name, "participant"):
+            logger.warning("%s %r is not one a participant may send; dropped", EVENT, name)
+            return
+        received = EventReceived(name=name, data=data, source="participant", identity=identity)
+        self.call.writing.write("event.received", received)
+
+    # Runs off the room's synchronous listener: the gateway's refusal is a warning, never a
+    # task's exception nobody reads.
+    def _answer(self, answering: Coroutine[object, object, None]) -> None:
+        async def answered() -> None:
+            try:
+                await answering
+            except PinecallError:
+                logger.warning("the widget's channel could not read the log", exc_info=True)
+
+        task = asyncio.create_task(answered())
+        self.answering.add(task)
+        task.add_done_callback(self.answering.discard)
+
+
+def _a_widget(seat: rtc.Participant) -> bool:
+    return seat.attributes.get(SCOPE_ATTRIBUTE, "") in READS_ITS_OWN_CALL
+
+
+def _decoded(data: bytes) -> JsonObject:
+    try:
+        return _A_JSON_OBJECT.validate_json(data)
+    except ValidationError:
+        return {}

pinecall/tenancy/admission.py

@@ -0,0 +1,204 @@
+"""Admission: an org's limits in a world against what it used there, before it uses more."""
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from pinecall.domain.errors import QuotaExhausted
+from pinecall.domain.names import Env
+from pinecall.domain.org import QuotaName, Quotas
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Connection, Pool
+from pinecall.process import box_settings
+from pinecall.tenancy import usage
+
+REFUSED = "the org has used {used} of its {limit} {quota} in the {env}"
+
+# Dollars are the same in both worlds: the month's spend in both is held to the one budget.
+BUDGET_REFUSED = "the org has spent {used} of its {limit} USD budget this month"
+
+
+ADMISSION = "admission"
+
+
+QUOTAS = """
+SELECT minutes, messages, agents, concurrent_calls, memory_facts, knowledge_chunks, numbers, seats,
+       llm_tokens, hosted_apps, budget_usd, lends
+FROM quotas WHERE org = %(org)s AND env = %(env)s
+"""
+
+
+# Replaced whole: a limit left out stops being one.
+SET_QUOTAS = """
+INSERT INTO quotas (org, env, minutes, messages, agents, concurrent_calls, memory_facts,
+                    knowledge_chunks, numbers, seats, llm_tokens, hosted_apps, budget_usd, lends)
+VALUES (%(org)s, %(env)s, %(minutes)s, %(messages)s, %(agents)s, %(concurrent_calls)s,
+        %(memory_facts)s, %(knowledge_chunks)s, %(numbers)s, %(seats)s, %(llm_tokens)s,
+        %(hosted_apps)s, %(budget_usd)s, %(lends)s)
+ON CONFLICT (org, env) DO UPDATE SET
+    minutes = excluded.minutes, messages = excluded.messages, agents = excluded.agents,
+    concurrent_calls = excluded.concurrent_calls, memory_facts = excluded.memory_facts,
+    knowledge_chunks = excluded.knowledge_chunks, numbers = excluded.numbers,
+    seats = excluded.seats, llm_tokens = excluded.llm_tokens,
+    hosted_apps = excluded.hosted_apps, budget_usd = excluded.budget_usd, lends = excluded.lends,
+    set_at = now()
+"""
+
+
+@dataclass(frozen=True)
+class Ceiling:
+    """How long a call admitted may last: what is left of the org's minutes."""
+
+    seconds: int
+    minutes: int
+
+
+class Admission(BaseModel):
+    """What a newborn org may use in each world: a person's first org, and any later one."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    # A world the row does not name has no limits.
+    first: dict[Env, Quotas] = Field(default_factory=dict[Env, Quotas])
+    # None gives a later org what the first got; set, one trial per person.
+    later: dict[Env, Quotas] | None = None
+
+
+# `at` is the log's clock, so a call is held to the month its summary will be counted in.
+async def admit_call(pool: Pool, org: str, env: Env, *, running: int, at: float) -> Ceiling | None:
+    """Admit one more call, with its ceiling; None when the org's minutes have no limit."""
+    quotas = await quotas_of(pool, org, env)
+    _refuse_past(quotas, env, "concurrent_calls", running)
+    month = usage.month_of(at)
+    if quotas.budget_usd is not None:
+        _refuse_over_budget(quotas, await usage.spent_in(pool, org, month))
+    if quotas.minutes is None and quotas.messages is None and quotas.llm_tokens is None:
+        return None
+    spent = await usage.used(pool, org, env, month)
+    _refuse_past(quotas, env, "minutes", spent.minutes)
+    _refuse_past(quotas, env, "messages", spent.messages)
+    _refuse_past(quotas, env, "llm_tokens", spent.input_tokens + spent.output_tokens)
+    if quotas.minutes is None:
+        return None
+    # Never zero: the worker reads a zero ceiling as none.
+    seconds = max(1, int((quotas.minutes - spent.minutes) * 60))
+    return Ceiling(seconds=seconds, minutes=quotas.minutes)
+
+
+# A call is counted at its summary, so a long written call adds what it has used so far.
+async def admit_turn(pool: Pool, scope: Scope, *, turns: int, tokens: int, at: float) -> None:
+    """Admit one more turn of a written call already this long."""
+    org, env = scope.org, scope.env
+    quotas = await quotas_of(pool, org, env)
+    if quotas.messages is None and quotas.llm_tokens is None:
+        return
+    spent = await usage.used(pool, org, env, usage.month_of(at))
+    _refuse_past(quotas, env, "messages", spent.messages + turns)
+    _refuse_past(quotas, env, "llm_tokens", spent.input_tokens + spent.output_tokens + tokens)
+
+
+async def admit_agent(pool: Pool, org: str, env: Env, *, holding: int) -> None:
+    """Admit one more agent held by the org's apps."""
+    _refuse_past(await quotas_of(pool, org, env), env, "agents", holding)
+
+
+async def admit_number(pool: Pool, org: str, env: Env, *, bought: int) -> None:
+    """Admit one more number bought on the box's carrier account for the org."""
+    _refuse_past(await quotas_of(pool, org, env), env, "numbers", bought)
+
+
+async def admit_memory(pool: Pool, org: str, env: Env, *, kept: int) -> None:
+    """Admit one more fact remembered about a contact."""
+    _refuse_past(await quotas_of(pool, org, env), env, "memory_facts", kept)
+
+
+async def admit_seat(pool: Pool, org: str, env: Env, *, seated: int) -> None:
+    """Admit one more person seated in the org."""
+    _refuse_past(await quotas_of(pool, org, env), env, "seats", seated)
+
+
+async def admit_hosted_app(pool: Pool, org: str, env: Env, *, hosting: int) -> None:
+    """Admit one more app the box hosts for the org."""
+    _refuse_past(await quotas_of(pool, org, env), env, "hosted_apps", hosting)
+
+
+# Sized up front: a push that would pass the limit is refused whole.
+async def admit_push(pool: Pool, org: str, env: Env, *, keeping: int) -> None:
+    """Admit a push that leaves the org keeping this many knowledge chunks."""
+    quotas = await quotas_of(pool, org, env)
+    limit = quotas.exceeded("knowledge_chunks", keeping)
+    if limit is not None:
+        _refused(env, "knowledge_chunks", keeping, limit)
+
+
+async def quotas_of(pool: Pool, org: str, env: Env) -> Quotas:
+    """The org's limits in the world; none when nobody set them."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(QUOTAS, {"org": org, "env": env})).fetchone()
+    if row is None:
+        return Quotas()
+    lends = row.pop("lends")
+    return Quotas(**row, lends=None if lends is None else frozenset(lends))
+
+
+async def set_quotas(pool: Pool, org: str, env: Env, quotas: Quotas) -> None:
+    """Replace the org's limits in the world, whole."""
+    async with pool.connection() as connection:
+        await _set_quotas(connection, org, env, quotas)
+
+
+async def admission(pool: Pool) -> Admission:
+    """What a newborn org is given; nothing limited on a box that never said."""
+    async with pool.connection() as connection:
+        return await _admission(connection)
+
+
+async def set_admission(pool: Pool, allowed: Admission) -> None:
+    """Write what a newborn org is given, whole, as the console's box screen sends it."""
+    async with pool.connection() as connection:
+        await box_settings.write(connection, ADMISSION, allowed.model_dump(mode="json"))
+
+
+async def give_first_quotas(connection: Connection, org: str, *, already: int) -> None:
+    """Set a newborn org's quotas in each world, as the box's admission says for its person."""
+    allowed = await _admission(connection)
+    worlds = allowed.first if allowed.later is None or already == 0 else allowed.later
+    for env, quotas in worlds.items():
+        await _set_quotas(connection, org, env, quotas)
+
+
+def _refuse_past(quotas: Quotas, env: Env, quota: QuotaName, spent: float) -> None:
+    limit = quotas.reached(quota, spent)
+    if limit is not None:
+        _refused(env, quota, spent, limit)
+
+
+def _refused(env: Env, quota: QuotaName, spent: float, limit: int) -> None:
+    sentence = REFUSED.format(
+        used=_shown(spent), limit=limit, quota=quota.replace("_", " "), env=env
+    )
+    raise QuotaExhausted(sentence, quota=quota, used=spent, limit=limit)
+
+
+def _refuse_over_budget(quotas: Quotas, spent: float) -> None:
+    limit = quotas.reached("budget_usd", spent)
+    if limit is not None:
+        sentence = BUDGET_REFUSED.format(used=_shown(spent), limit=limit)
+        raise QuotaExhausted(sentence, quota="budget_usd", used=spent, limit=limit)
+
+
+def _shown(spent: float) -> int | float:
+    return int(spent) if float(spent).is_integer() else round(spent, 2)
+
+
+async def _admission(connection: Connection) -> Admission:
+    value = await box_settings.read(connection, ADMISSION)
+    return Admission() if value is None else Admission.model_validate(value)
+
+
+async def _set_quotas(connection: Connection, org: str, env: Env, quotas: Quotas) -> None:
+    lends = None if quotas.lends is None else sorted(quotas.lends)
+    await connection.execute(
+        SET_QUOTAS,
+        {"org": org, "env": env, **quotas.limits, "lends": lends},
+    )

pinecall/tenancy/agents.py

@@ -0,0 +1,164 @@
+"""What an org sets per agent: how its widget looks, and its hold melody."""
+
+import hashlib
+import re
+from dataclasses import asdict, dataclass
+from typing import Literal
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool
+from pinecall.wire.parts import WidgetTheme
+
+# No row is the box's own melody; `off` is silence; `custom` an uploaded clip, converted once.
+type Played = Literal["off", "custom"]
+
+
+LONGEST = {"title": 80, "tagline": 160, "greeting": 500, "accent": 40}
+
+
+# The widget sets the accent as a CSS variable, so nothing that could end the declaration and
+# open another passes.
+A_COLOUR = re.compile(
+    r"^(#[0-9a-fA-F]{3,8}|[a-zA-Z]+|(rgb|rgba|hsl|hsla|oklch)\([0-9.,%\s/a-z-]+\))$"
+)
+
+
+LOOK = """
+SELECT title, tagline, greeting, accent, autostart, theme FROM agent_widgets
+WHERE org = %(org)s AND env = %(env)s AND agent = %(agent)s
+"""
+
+
+PUT_LOOK = """
+INSERT INTO agent_widgets (org, env, agent, title, tagline, greeting, accent, autostart, theme)
+VALUES (%(org)s, %(env)s, %(agent)s, %(title)s, %(tagline)s, %(greeting)s, %(accent)s,
+        %(autostart)s, %(theme)s)
+ON CONFLICT (org, env, agent) DO UPDATE SET
+    title = excluded.title, tagline = excluded.tagline, greeting = excluded.greeting,
+    accent = excluded.accent, autostart = excluded.autostart, theme = excluded.theme,
+    set_at = now()
+"""
+
+
+HOLD = """
+SELECT played, sha256, seconds, name FROM hold_audio
+WHERE org = %(org)s AND env = %(env)s AND agent = %(agent)s
+"""
+
+
+HOLD_AUDIO = (
+    "SELECT audio FROM hold_audio WHERE org = %(org)s AND env = %(env)s AND agent = %(agent)s"
+)
+
+
+KEEP_HOLD = """
+INSERT INTO hold_audio (org, env, agent, played, audio, sha256, seconds, name)
+VALUES (%(org)s, %(env)s, %(agent)s, %(played)s, %(audio)s, %(sha256)s, %(seconds)s, %(name)s)
+ON CONFLICT (org, env, agent) DO UPDATE SET
+    played = excluded.played, audio = excluded.audio, sha256 = excluded.sha256,
+    seconds = excluded.seconds, name = excluded.name, set_at = now()
+"""
+
+
+FORGET_HOLD = "DELETE FROM hold_audio WHERE org = %(org)s AND env = %(env)s AND agent = %(agent)s"
+
+
+@dataclass(frozen=True)
+class Look:
+    """How the widget presents the agent; None is the widget's own default."""
+
+    title: str | None = None
+    tagline: str | None = None
+    greeting: str | None = None
+    accent: str | None = None
+    autostart: bool = False
+    theme: WidgetTheme | None = None
+
+    def __post_init__(self) -> None:
+        text = {
+            "title": self.title,
+            "tagline": self.tagline,
+            "greeting": self.greeting,
+            "accent": self.accent,
+        }
+        for name, value in text.items():
+            longest = LONGEST[name]
+            if value is not None and len(value) > longest:
+                raise DeclarationRefused(f"a widget's {name} is {longest} characters at most")
+        if self.accent is not None and not A_COLOUR.match(self.accent):
+            raise DeclarationRefused(f"an accent is a CSS colour, not {self.accent!r}")
+
+
+@dataclass(frozen=True)
+class Chosen:
+    """What the agent plays while a tool runs: nothing, or a clip of its own."""
+
+    played: Played
+    sha256: str | None = None
+    seconds: float | None = None
+    name: str | None = None
+
+
+@dataclass(frozen=True)
+class Clip:
+    """An uploaded melody, already converted: its bytes, how long it lasts, the file's name."""
+
+    audio: bytes
+    seconds: float
+    name: str
+
+
+async def look_of(pool: Pool, scope: Scope, agent: str) -> Look:
+    """How the agent's widget looks in the world; the widget's defaults when nobody said."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(LOOK, _of(scope, agent))).fetchone()
+    return Look() if row is None else Look(**row)
+
+
+async def put_look(pool: Pool, scope: Scope, agent: str, look: Look) -> None:
+    """Replace how the agent's widget looks in the world."""
+    values = {**_of(scope, agent), **asdict(look)}
+    async with pool.connection() as connection:
+        await connection.execute(PUT_LOOK, values)
+
+
+async def hold_of(pool: Pool, scope: Scope, agent: str) -> Chosen | None:
+    """What the agent plays while a tool runs in the world; None is the box's melody."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(HOLD, _of(scope, agent))).fetchone()
+    return None if row is None else Chosen(**row)
+
+
+async def hold_audio(pool: Pool, scope: Scope, agent: str) -> bytes | None:
+    """The agent's own clip, when it plays one."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(HOLD_AUDIO, _of(scope, agent))).fetchone()
+    return None if row is None or row["audio"] is None else bytes(row["audio"])
+
+
+async def keep_hold(pool: Pool, scope: Scope, agent: str, clip: Clip) -> Chosen:
+    """Play this clip while the agent's tools run in the world."""
+    chosen = Chosen("custom", hashlib.sha256(clip.audio).hexdigest(), clip.seconds, clip.name)
+    await _kept_hold(pool, {**_of(scope, agent), **asdict(chosen), "audio": clip.audio})
+    return chosen
+
+
+async def silence_hold(pool: Pool, scope: Scope, agent: str) -> None:
+    """Play nothing while the agent's tools run; any clip is forgotten."""
+    await _kept_hold(pool, {**_of(scope, agent), **asdict(Chosen("off")), "audio": None})
+
+
+async def forget_hold(pool: Pool, scope: Scope, agent: str) -> None:
+    """Play the box's own melody again; any clip is forgotten."""
+    async with pool.connection() as connection:
+        await connection.execute(FORGET_HOLD, _of(scope, agent))
+
+
+async def _kept_hold(pool: Pool, values: dict[str, object]) -> None:
+    async with pool.connection() as connection:
+        await connection.execute(KEEP_HOLD, values)
+
+
+def _of(scope: Scope, agent: str) -> dict[str, object]:
+    return {"org": scope.org, "env": scope.env, "agent": agent}