pinecall-protocol 0.3.0__tar.gz → 0.6.14__tar.gz

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pinecall-protocol
-Version: 0.3.0
+Version: 0.6.14
 Summary: The Pinecall wire: pydantic models generated from the protocol schema
 Author-email: Bernardo Castro <me@bernardocastro.dev>
 License-Expression: Apache-2.0

pinecall_protocol-0.6.14/pinecall_protocol/_version.py

@@ -0,0 +1,4 @@
+"""Package version; hatch reads it at build time."""
+
+# 0.0.0 means "unreleased". Set by the maintainer; never bumped from code.
+__version__ = "0.6.14"

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/commands.py

@@ -17,12 +17,17 @@ class AgentConfigure(WireModel):
     config: AgentConfig
 
 
+class AgentDrain(WireModel):
+    """This socket is leaving, and its calls go on without it."""
+
+
 # The gateway answers agent.registered, or error.
 class AgentRegister(WireModel):
     """The app's first message: this socket speaks for this agent and answers these doors."""
 
     routes: list[Route]
     sdk: str | None = None
+    host: str | None = None
     takes_unclaimed: bool = True
 
 
@@ -45,6 +50,30 @@ class AgentSay(WireModel):
     allow_interruptions: bool | None = None
 
 
+# Ask for a person without sending the caller anywhere: the call waits on hold until a supervisor
+# takes the line, or until wait_s passes with nobody taking it. attention.answered says which.
+class CallAttention(WireModel):
+    """Ask for a person without sending the caller anywhere."""
+
+    reason: str
+    wait_s: float
+
+
+# Lands as callback.requested with via agent; placing the call is the app's.
+class CallCallback(WireModel):
+    """Write down that the caller wants to be called back."""
+
+    number: str
+    when: str | None = None
+    note: str | None = None
+
+
+class CallClaim(WireModel):
+    """The code the caller said, to bind this call to the page that shows it."""
+
+    code: str = Field(pattern="^[0-9]{4}$")
+
+
 # The new call's log opens with call.dialing; call.started follows when the far end answers.
 class CallDial(WireModel):
     """Place an outbound call as this agent."""
@@ -94,12 +123,12 @@ class CallMute(WireModel):
     """Mute the agent: it keeps listening and thinking, produces no audio."""
 
 
-# call.transferred says whether it worked.
+# call.transferred says whether it worked, and which mode it was.
 class CallTransfer(WireModel):
-    """Send the caller to another number."""
+    """Send the caller to another number, or bring that number into the call."""
 
     to: str
-    mode: TransferMode
+    mode: TransferMode | None = None
 
 
 class CallUnhold(WireModel):

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/defs.py

@@ -25,16 +25,17 @@ type Env = Literal["production", "sandbox"]
 
 
 # What a console may ask of the process standing in the agent's directory, relayed by the gateway: a
-# written call to the class mounted there (chat), a simulated caller from its personas, its goldens
-# and a suite of them, its knowledge folder pushed or its golden asked, its memory goldens, a call
-# promoted to a candidate file, the drift of the last two windows, and the reproductions a broken
-# run left on that disk. Everything else a console needs is a door of the gateway.
+# written call to the class mounted there (chat), a simulated caller put on the class it holds, its
+# goldens and a suite of them, its knowledge folder pushed or its golden asked, its memory goldens,
+# the panel it draws beside a conversation (view), a call promoted to a candidate file, the drift of
+# the last two windows, and the reproductions a broken run left on that disk. Everything else a
+# console needs is a door of the gateway.
 type DevVerb = Literal[
     "chat.roster",
     "chat.start",
     "chat.say",
     "chat.end",
-    "simulate.roster",
+    "view.render",
     "simulate.start",
     "goldens.roster",
     "goldens.run",
@@ -81,8 +82,9 @@ type EndedBy = Literal["caller", "agent", "supervisor", "platform"]
 type ScoreVerdict = Literal["held", "broken", "deferred", "skipped"]
 
 
-# Cold: the caller is sent on and the agent leaves. Warm: the agent stays on the line until the
-# other side answers, then leaves.
+# Cold: the caller is sent on with a REFER on their SIP leg and the call ends here. Warm: the number
+# is dialled into the call's own room, the agent stays on the line until the other side answers and
+# then falls silent; the call ends when either of them hangs up.
 type TransferMode = Literal["cold", "warm"]
 
 
@@ -235,6 +237,7 @@ class DocSource(WireModel):
     """One chunk of the knowledge base that retrieval put in front of the model for this turn."""
 
     id: str
+    base: str | None = None
     path: str
     heading: str | None = None
     score: float
@@ -310,6 +313,8 @@ class TurnConfig(WireModel):
 
     min_interruption_words: int | None = None
     endpointing_ms: int | None = None
+    eot_threshold: float | None = None
+    eager_eot_threshold: float | None = None
 
 
 # How the voice says one word it would otherwise get wrong: a proper name, a brand, a street.
@@ -328,6 +333,16 @@ class StateFieldSpec(WireModel):
     visibility: Visibility
 
 
+# The panel the agent draws beside a conversation: it is declared here so a console knows the agent
+# has one before it asks for it, and draws its own about the contact when it has not. What the panel
+# CONTAINS never comes this way — it is asked for a conversation at a time, through the view.render
+# dev verb.
+class ViewSpec(WireModel):
+    """The panel the agent draws beside a conversation."""
+
+    name: str
+
+
 # An event nobody declared is refused before it touches the log.
 class EventSpec(WireModel):
     """One outside event the agent accepts, and from whom."""
@@ -337,7 +352,7 @@ class EventSpec(WireModel):
 
 
 class KnowledgeFile(WireModel):
-    """One file of knowledge, sent whole: its path as the tenant keeps it, and its text."""
+    """One file of a base, as a push sends it: its path as the tenant keeps it, and its text."""
 
     path: str
     text: str
@@ -384,8 +399,11 @@ class MemoryConfig(WireModel):
     forget: list[str] = Field(default_factory=list[str])
 
 
-# What an app declares about its agent: the voice, the models, the language, the greeting, the
-# tools, and who may see and send what. Every field is optional so a configure can change one thing.
+# What an app declares about its agent: the prompt's layout, the language, the tools, whether it
+# searches its bases itself, and who may see and send what. Every field is optional so a configure
+# can change one thing. The environment — voice, models, greeting, hangup, turn, says, hears,
+# knowledge, docs, memory — is the world's, set in the agent's settings, and no longer read off this
+# declaration.
 class AgentConfig(WireModel):
     """What an app declares about its agent."""
 
@@ -402,6 +420,9 @@ class AgentConfig(WireModel):
     docs: DocsConfig | None = None
     memory: MemoryConfig | None = None
     hangup: HangupConfig | None = None
+    record: bool = True
     tools: list[ToolSpec] | None = None
+    uses_knowledge: bool = False
     state_fields: list[StateFieldSpec] | None = None
+    view: ViewSpec | None = None
     events: list[EventSpec] | None = None

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/events.py

@@ -17,6 +17,7 @@ from pinecall_protocol.defs import (
     EndReason,
     Env,
     MemoryOp,
+    Projection,
     Route,
     ScoreVerdict,
     Supervisor,
@@ -42,6 +43,15 @@ class AgentDetached(WireModel):
     left: bool
 
 
+class AgentDraining(WireModel):
+    """One socket let go of its calls without cutting them."""
+
+    app: str
+    env: Env
+    handed: int
+    parked: int
+
+
 # The gateway accepted an agent.register: this socket now speaks for the agent and answers its
 # routes. Many sockets may hold one agent at once — a new call takes the newest of them, unless the
 # caller names one by its `app` id.
@@ -74,6 +84,59 @@ class AgentTranscript(WireModel):
     end: float | None = None
 
 
+# An ask for a person settled: a supervisor took the line, or the wait ran out and the agent has the
+# caller back.
+class AttentionAnswered(WireModel):
+    """An ask for a person settled."""
+
+    ok: bool
+    by: Supervisor | None
+    error: str | None = None
+
+
+# The agent asked for a person: the caller is on hold and waits for a supervisor to take the line.
+# What a supervisor's console and phone are notified by.
+class AttentionRequested(WireModel):
+    """The agent asked for a person."""
+
+    reason: str
+    wait_s: float
+
+
+# Everything the agent says and hears comes after this.
+class CallStarted(WireModel):
+    """Media is up: the caller and the agent can hear each other, or the text session is open."""
+
+    channel: Channel
+    direction: Direction
+    from_: str = Field(alias="from")
+    to: str
+    run: str | None = None
+    persona: str | None = None
+    accepts_when: str | None = None
+    declines_when: str | None = None
+    caller: Contact | None
+    started_at: float
+    env: Env | None = None
+
+
+class CallAttached(WireModel):
+    """A call changed hands without ending."""
+
+    app: str
+    started: CallStarted
+    state: dict[str, Any]
+    seq: int
+    claimed: str | None = None
+
+
+class CallClaimed(WireModel):
+    """The call was bound to a page's code."""
+
+    code: str
+    via: Literal["keypad", "agent"]
+
+
 # The first entry of an outbound call's log.
 class CallDialing(WireModel):
     """The platform is placing an outbound call and the far end has not answered yet."""
@@ -150,20 +213,6 @@ class CallScore(WireModel):
     judge_cost_eur: float | None = None
 
 
-# Everything the agent says and hears comes after this.
-class CallStarted(WireModel):
-    """Media is up: the caller and the agent can hear each other, or the text session is open."""
-
-    channel: Channel
-    direction: Direction
-    from_: str = Field(alias="from")
-    to: str
-    run: str | None = None
-    caller: Contact | None
-    started_at: float
-    env: Env | None = None
-
-
 # Written after call.ended, once memory and pricing are done; call.score follows it and seals the
 # log.
 class CallSummary(WireModel):
@@ -182,24 +231,42 @@ class CallTransferred(WireModel):
     """A transfer asked for by the agent or a supervisor finished, one way or the other."""
 
     to: str
-    mode: TransferMode
+    mode: TransferMode | None = None
     ok: bool
     error: str | None = None
 
 
-# Somebody asked to be called back because no seat was free: a phone caller the overflow agent
-# answered, or a web visitor who left a number at the widget. Written into the agent's own log; the
-# tenant's app reads it and places the call.
+# Somebody asked to be called back: a phone caller the overflow agent answered, a web visitor who
+# left a number at the widget, or a caller who asked the agent for one (call.callback). Written into
+# the agent's own log; the tenant's app reads it and places the call.
 class CallbackRequested(WireModel):
-    """Somebody asked to be called back because no seat was free."""
+    """Somebody asked to be called back."""
 
     channel: Channel
     number: str
-    via: Literal["overflow", "widget"]
+    via: Literal["overflow", "widget", "agent"]
     call: str | None
+    when: str | None = None
+    note: str | None = None
     contact: Contact | None
 
 
+class CodeClaimed(WireModel):
+    """One code, taken or expired."""
+
+    code: str
+    call: str | None
+
+
+class CodeIssued(WireModel):
+    """One code, waiting for the call that keys it."""
+
+    code: str
+    env: Env
+    expires_at: float
+    log: Projection
+
+
 # The tool does not run; the model is told.
 class ConfirmDeclined(WireModel):
     """The caller did not say yes, or the request lapsed."""
@@ -235,9 +302,10 @@ class ConfirmRequest(WireModel):
     ttl_s: int
 
 
+# The gateway refused a call, a written turn or a register because one of the org's quotas ran out.
 # Written into the agent's own log, which is the org's, before the door says no.
 class CreditsExhausted(WireModel):
-    """The gateway refused a call or a register because one of the org's quotas ran out."""
+    """CreditsExhausted, as protocol/schema declares it."""
 
     org: str
     quota: Literal[
@@ -249,6 +317,7 @@ class CreditsExhausted(WireModel):
         "knowledge_chunks",
         "numbers",
         "seats",
+        "llm_tokens",
     ]
     used: float
     limit: int
@@ -280,6 +349,13 @@ class DocsSources(WireModel):
     speech_id: str | None = None
 
 
+class DtmfReceived(WireModel):
+    """One tone the caller keyed."""
+
+    digit: Literal["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"]
+    code: int
+
+
 # Inside a call it says what failed; outside a call it says which command the gateway refused.
 class ErrorEvent(WireModel):
     """Something went wrong."""
@@ -328,6 +404,27 @@ class MemoryOps(WireModel):
     speech_id: str | None = None
 
 
+class MessageTaken(WireModel):
+    """One waiting message, off the queue."""
+
+    message_id: str
+    call: str | None
+
+
+class MessageWaiting(WireModel):
+    """One message, kept until somebody can answer it."""
+
+    channel: Channel
+    env: Env
+    number: str
+    phone_number_id: str
+    from_: str = Field(alias="from")
+    name: str | None
+    message_id: str
+    text: str
+    received_at: float
+
+
 # Ephemeral: it proves the socket is alive and says nothing else.
 class Pong(WireModel):
     """The answer to ping."""
@@ -408,7 +505,7 @@ class SupervisorTransferred(WireModel):
 
     by: Supervisor
     to: str
-    mode: TransferMode
+    mode: TransferMode | None = None
 
 
 class SupervisorWhispered(WireModel):

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/fixtures/__init__.py

@@ -1,4 +1,4 @@
-"""The golden call log and the state it reduces to: every consumer proves the same thing."""
+"""Paths to the golden call log and the state it reduces to, shared by every language's tests."""
 
 from importlib.resources import files
 from pathlib import Path

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/fixtures/call-log-golden.state.json

@@ -30,6 +30,7 @@
   "held": false,
   "muted": false,
   "transfer": null,
+  "attention": null,
   "usage": [{"input_audio_tokens": 0, "input_cache_creation_tokens": 562, "input_cached_audio_tokens": 0, "input_cached_image_tokens": 0, "input_cached_text_tokens": 0, "input_cached_tokens": 13145, "input_image_tokens": 0, "input_text_tokens": 0, "input_tokens": 14963, "model": "claude-haiku-4-5", "output_audio_tokens": 0, "output_reasoning_tokens": 0, "output_text_tokens": 0, "output_tokens": 281, "provider": "anthropic", "session_duration": 0.0, "type": "llm_usage"}, {"audio_duration": 25.6, "characters_count": 397, "input_tokens": 0, "model": "eleven_flash_v2_5", "output_tokens": 0, "provider": "elevenlabs", "type": "tts_usage"}, {"audio_duration": 12.1, "input_tokens": 0, "model": "stt-rt-v5", "output_tokens": 0, "provider": "soniox", "type": "stt_usage"}, {"model": "adaptive", "provider": "livekit", "total_requests": 12, "type": "interruption_usage"}, {"model": "turn-detector-v1", "provider": "livekit", "total_requests": 5, "type": "eot_usage"}],
   "cost": {"eur": 0.022937, "rate": {"as_of": "2026-08-12", "currency": "EUR", "usd_to_eur": 0.92}, "rows": [{"eur": 0.001156, "model": "claude-haiku-4-5", "provider": "anthropic", "quantity": 1256.0, "unit": "input_tokens", "unit_price_usd": 1e-06}, {"eur": 0.001209, "model": "claude-haiku-4-5", "provider": "anthropic", "quantity": 13145.0, "unit": "cached_input_tokens", "unit_price_usd": 1e-07}, {"eur": 0.000646, "model": "claude-haiku-4-5", "provider": "anthropic", "quantity": 562.0, "unit": "cache_creation_tokens", "unit_price_usd": 1.25e-06}, {"eur": 0.001293, "model": "claude-haiku-4-5", "provider": "anthropic", "quantity": 281.0, "unit": "output_tokens", "unit_price_usd": 5e-06}, {"eur": 0.018262, "model": "eleven_flash_v2_5", "provider": "elevenlabs", "quantity": 397.0, "unit": "characters", "unit_price_usd": 5e-05}, {"eur": 0.000371, "model": "stt-rt-v5", "provider": "soniox", "quantity": 12.1, "unit": "audio_seconds", "unit_price_usd": 3.33e-05}], "unpriced": [{"model": "adaptive", "provider": "livekit"}, {"model": "turn-detector-v1", "provider": "livekit"}]},
   "routes": [],

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/registry.py

@@ -5,9 +5,13 @@ from typing import Literal
 from pinecall_protocol._base import WireModel
 from pinecall_protocol.commands import (
     AgentConfigure,
+    AgentDrain,
     AgentRegister,
     AgentReply,
     AgentSay,
+    CallAttention,
+    CallCallback,
+    CallClaim,
     CallDial,
     CallDtmf,
     CallEvent,
@@ -34,11 +38,16 @@ from pinecall_protocol.defs import ToolResult
 from pinecall_protocol.events import (
     AgentConfigured,
     AgentDetached,
+    AgentDraining,
     AgentRegistered,
     AgentStateChanged,
     AgentTranscript,
     AgentTurnEnded,
+    AttentionAnswered,
+    AttentionRequested,
+    CallAttached,
     CallbackRequested,
+    CallClaimed,
     CallDialing,
     CallEnded,
     CallLine,
@@ -47,6 +56,8 @@ from pinecall_protocol.events import (
     CallStarted,
     CallSummary,
     CallTransferred,
+    CodeClaimed,
+    CodeIssued,
     ConfirmDeclined,
     ConfirmGranted,
     ConfirmRequest,
@@ -54,11 +65,14 @@ from pinecall_protocol.events import (
     Custom,
     DevRequest,
     DocsSources,
+    DtmfReceived,
     ErrorEvent,
     FleetFull,
     LogCaughtUp,
     LogGap,
     MemoryOps,
+    MessageTaken,
+    MessageWaiting,
     Pong,
     PromptChanged,
     StateChanged,
@@ -100,9 +114,14 @@ from pinecall_protocol.room import (
 EVENTS: dict[str, type[WireModel]] = {
     "agent.configured": AgentConfigured,
     "agent.detached": AgentDetached,
+    "agent.draining": AgentDraining,
     "agent.registered": AgentRegistered,
     "agent.state": AgentStateChanged,
     "agent.transcript": AgentTranscript,
+    "attention.answered": AttentionAnswered,
+    "attention.requested": AttentionRequested,
+    "call.attached": CallAttached,
+    "call.claimed": CallClaimed,
     "call.dialing": CallDialing,
     "call.ended": CallEnded,
     "call.line": CallLine,
@@ -112,6 +131,8 @@ EVENTS: dict[str, type[WireModel]] = {
     "call.summary": CallSummary,
     "call.transferred": CallTransferred,
     "callback.requested": CallbackRequested,
+    "code.claimed": CodeClaimed,
+    "code.issued": CodeIssued,
     "confirm.declined": ConfirmDeclined,
     "confirm.granted": ConfirmGranted,
     "confirm.request": ConfirmRequest,
@@ -119,12 +140,15 @@ EVENTS: dict[str, type[WireModel]] = {
     "custom": Custom,
     "dev.request": DevRequest,
     "docs.sources": DocsSources,
+    "dtmf.received": DtmfReceived,
     "error": ErrorEvent,
     "event.received": EventReceived,
     "fleet.full": FleetFull,
     "log.caught_up": LogCaughtUp,
     "log.gap": LogGap,
     "memory.ops": MemoryOps,
+    "message.taken": MessageTaken,
+    "message.waiting": MessageWaiting,
     "metrics.avatar": AvatarMetrics,
     "metrics.eot": EOTInferenceMetrics,
     "metrics.eou": EOUMetrics,
@@ -162,9 +186,14 @@ EVENTS: dict[str, type[WireModel]] = {
 type EventType = Literal[
     "agent.configured",
     "agent.detached",
+    "agent.draining",
     "agent.registered",
     "agent.state",
     "agent.transcript",
+    "attention.answered",
+    "attention.requested",
+    "call.attached",
+    "call.claimed",
     "call.dialing",
     "call.ended",
     "call.line",
@@ -174,6 +203,8 @@ type EventType = Literal[
     "call.summary",
     "call.transferred",
     "callback.requested",
+    "code.claimed",
+    "code.issued",
     "confirm.declined",
     "confirm.granted",
     "confirm.request",
@@ -181,12 +212,15 @@ type EventType = Literal[
     "custom",
     "dev.request",
     "docs.sources",
+    "dtmf.received",
     "error",
     "event.received",
     "fleet.full",
     "log.caught_up",
     "log.gap",
     "memory.ops",
+    "message.taken",
+    "message.waiting",
     "metrics.avatar",
     "metrics.eot",
     "metrics.eou",
@@ -246,9 +280,13 @@ TERMINAL_EVENT: str = "call.score"
 # Every command by its wire type; codec looks the model up here.
 COMMANDS: dict[str, type[WireModel]] = {
     "agent.configure": AgentConfigure,
+    "agent.drain": AgentDrain,
     "agent.register": AgentRegister,
     "agent.reply": AgentReply,
     "agent.say": AgentSay,
+    "call.attention": CallAttention,
+    "call.callback": CallCallback,
+    "call.claim": CallClaim,
     "call.dial": CallDial,
     "call.dtmf": CallDtmf,
     "call.event": CallEvent,
@@ -275,9 +313,13 @@ COMMANDS: dict[str, type[WireModel]] = {
 
 type CommandType = Literal[
     "agent.configure",
+    "agent.drain",
     "agent.register",
     "agent.reply",
     "agent.say",
+    "call.attention",
+    "call.callback",
+    "call.claim",
     "call.dial",
     "call.dtmf",
     "call.event",
@@ -306,9 +348,13 @@ type CommandType = Literal[
 # Which events a command lands in the log as, so a caller knows what to wait for.
 PRODUCES: dict[str, tuple[str, ...]] = {
     "agent.configure": ("agent.configured",),
+    "agent.drain": ("agent.draining",),
     "agent.register": ("agent.registered",),
     "agent.reply": ("turn.agent",),
     "agent.say": ("turn.agent",),
+    "call.attention": ("attention.requested", "call.line", "attention.answered"),
+    "call.callback": ("callback.requested",),
+    "call.claim": ("call.claimed",),
     "call.dial": ("call.dialing",),
     "call.dtmf": (),
     "call.event": ("event.received",),

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/rest.py

@@ -10,13 +10,19 @@ from pinecall_protocol.defs import (
     Contact,
     Cost,
     Direction,
+    DocsConfig,
     EndReason,
     Env,
+    GreetingConfig,
+    HangupConfig,
     KnowledgeFile,
+    MemoryConfig,
     PlatformTool,
+    Pronunciation,
+    TurnConfig,
 )
 from pinecall_protocol.envelope import Entry
-from pinecall_protocol.state import CallStatus, State
+from pinecall_protocol.state import AttentionState, CallStatus, State
 
 
 class CallState(WireModel):
@@ -72,6 +78,15 @@ class SessionLine(WireModel):
     cost: Cost | None
     score: SessionScore | None = None
     flags: list[SessionFlag] | None = None
+    attention: AttentionState | None = None
+
+
+# The operator's stream, every org of the box at once.
+class BoxEvent(WireModel):
+    """One frame of GET /v1/ops/events: an entry of some org's floor, and whose floor it is."""
+
+    org: str
+    entry: Entry
 
 
 # GET /v1/agents/{slug}/sessions and GET /v1/sessions: the calls that match, newest first, a page at
@@ -132,6 +147,29 @@ class Insights(WireModel):
     budget: InsightsBudget
 
 
+class Limit(WireModel):
+    """One quota: the limit the org was given, and how much of it is used."""
+
+    limit: int | None
+    used: float
+
+
+# GET /v1/limits: what the key's org may use and has used on this instance, where it bought more,
+# and which of the box's vendor keys it runs on. Any key of the org.
+class Limits(WireModel):
+    """GET /v1/limits."""
+
+    minutes: Limit
+    messages: Limit
+    llm_tokens: Limit
+    concurrent_calls: Limit
+    agents: Limit
+    seats: Limit
+    numbers: Limit
+    lends: list[str] | None
+    billing_url: str | None
+
+
 # GET and PUT /v1/org/judging: whether the org's calls are judged at hang-up, and what judging one
 # may spend on a model.
 class Judging(WireModel):
@@ -229,6 +267,11 @@ class AgentMemory(WireModel):
     next: str | None
 
 
+# auto: the visitor's own light or dark, as the browser says. light and dark: that one, whatever the
+# browser says.
+type WidgetTheme = Literal["auto", "light", "dark"]
+
+
 # GET and PUT /v1/agents/{slug}/widget: how the widget presents this agent, kept per org, world and
 # agent. PUT takes the whole set.
 class WidgetSettings(WireModel):
@@ -239,6 +282,7 @@ class WidgetSettings(WireModel):
     greeting: str | None
     accent: str | None
     autostart: bool
+    theme: WidgetTheme | None = None
 
 
 # GET and PUT /v1/org/sso: the OpenID Connect provider this org's people sign in at, and never the
@@ -412,6 +456,38 @@ class AgentList(WireModel):
     agents: list[HeldAgent]
 
 
+# One app connected to the gateway right now: one process on one machine, holding one or more agents
+# in one world.
+class AppProcess(WireModel):
+    """One app connected to the gateway right now."""
+
+    app: str
+    agents: list[str]
+    env: Env
+    host: str | None
+    address: str | None
+    sdk: str | None
+    holder: LineHolder | None
+    connected_at: float
+
+
+# GET /v1/apps: every app connected in the request's world that this key may see — its own corner's
+# and the org's, every corner's with `team`.
+class AppList(WireModel):
+    """GET /v1/apps."""
+
+    apps: list[AppProcess]
+
+
+# POST /v1/apps/{app}/stop, the answer: the socket was closed with the stop code, and the app exits
+# rather than reconnect.
+class AppStopped(WireModel):
+    """POST /v1/apps/{app}/stop, the answer."""
+
+    app: str
+    stopped: bool
+
+
 # GET /v1/agents/{slug}/line: whose terminal a call that RINGS at this agent's doors lands in. An
 # org shares one sandbox number, so it rings in one place and which one is claimed.
 class TheLine(WireModel):
@@ -643,8 +719,9 @@ class ExtractionRun(WireModel):
 
 
 # POST /v1/calls/{call}/lookup, the body: which platform tool to run for this turn, and what to run
-# it with. Worker-only; the gateway runs it against its own stores and writes memory.ops or
-# docs.sources on the call's log itself.
+# it with. Asked by the worker for the call it serves, and by the app for a call of its own org —
+# `this.knowledge.search` in a tool; the gateway runs it against its own stores and writes
+# memory.ops or docs.sources on the call's log itself.
 class LookupRequest(WireModel):
     """POST /v1/calls/{call}/lookup, the body."""
 
@@ -663,6 +740,22 @@ class LookupResult(WireModel):
     took_ms: float
 
 
+class FoundChunk(WireModel):
+    """One chunk search found: the file it came from, the heading it sits under, and its text."""
+
+    path: str
+    heading: str | None
+    text: str
+
+
+# What search answers in a lookup's output: the best chunks of every base the agent reads, the best
+# first. The app's `this.knowledge.search` hands the chunks to the tool that asked.
+class SearchFound(WireModel):
+    """What search answers in a lookup's output."""
+
+    chunks: list[FoundChunk]
+
+
 # POST /v1/calls/{call}/remember, the answer: what the call taught about the contact, counted.
 # Worker-only; the body is empty, the gateway reads the turns off its own log and writes memory.ops
 # itself.
@@ -683,6 +776,41 @@ class Dialled(WireModel):
     to: str
     from_: str = Field(alias="from")
     env: Env
+    log_token: str
+
+
+# POST /v1/codes, the answer: the four digits a page shows beside the agent's number, when they stop
+# being a code, and the token the page asks about them with.
+class Code(WireModel):
+    """POST /v1/codes, the answer."""
+
+    code: str
+    number: str
+    expires_at: float
+    code_token: str
+
+
+# GET /v1/codes/{code}: whether a call has claimed the code yet, and once one has, the call and the
+# token that reads it.
+class CodeStanding(WireModel):
+    """GET /v1/codes/{code}."""
+
+    code: str
+    status: Literal["waiting", "claimed", "expired"]
+    expires_at: float
+    call: str | None
+    log_token: str | None
+
+
+# POST /v1/tokens, the answer: where the browser joins, as whom, the call it becomes, and a token
+# that reads that call's log.
+class Minted(WireModel):
+    """POST /v1/tokens, the answer."""
+
+    server_url: str
+    participant_token: str
+    call: str
+    log_token: str
 
 
 class DialGuards(WireModel):
@@ -713,3 +841,312 @@ class OutboundProvisioned(WireModel):
     ready: bool
     trunk: str | None = None
     address: str | None = None
+
+
+# Every field is optional; one left out is not set, and the runtime's own default stands for it.
+class TuningBody(WireModel):
+    """An agent's settings: what the org set, per world and per corner."""
+
+    voice: str | None = None
+    tts: str | None = None
+    tts_model: str | None = None
+    stt: str | None = None
+    llm: str | None = None
+    greeting: GreetingConfig | None = None
+    hangup: HangupConfig | None = None
+    turn: TurnConfig | None = None
+    memory: MemoryConfig | None = None
+    record: bool | None = None
+    max_duration_s: int | None = None
+    knowledge: str | None = None
+    bases: list[DocsConfig] | None = None
+
+
+# One kept version of an agent's tuning: whose corner, which version, who set it and when, and what
+# it says.
+class TuningRow(WireModel):
+    """One kept version of an agent's tuning."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: float
+    config: TuningBody
+
+
+# GET /v1/agents/{slug}/settings: the agent's tuning as this key sees it — its own corner's, the
+# team's and production's, each corner's own newest row, or null when that corner set nothing.
+class TuningAnswer(WireModel):
+    """GET /v1/agents/{slug}/settings."""
+
+    world: Env
+    yours: TuningRow | None
+    team: TuningRow | None
+    production: TuningRow | None
+
+
+# PUT /v1/agents/{slug}/settings, the body: the whole set, the version it was read at, why, and
+# whose corner.
+class TuningPut(WireModel):
+    """PUT /v1/agents/{slug}/settings, the body."""
+
+    config: TuningBody
+    if_version: int | None = None
+    note: str | None = None
+    team: bool = False
+
+
+class TuningHistory(WireModel):
+    """GET /v1/agents/{slug}/settings/history: one corner's versions, newest first."""
+
+    world: Env
+    holder: str
+    rows: list[TuningRow]
+
+
+# GET /v1/agents/{slug}/settings/diff: what this key's corner reads against another corner's newest,
+# and which fields differ.
+class TuningDiff(WireModel):
+    """GET /v1/agents/{slug}/settings/diff."""
+
+    ours: TuningRow | None
+    theirs: TuningRow | None
+    changed: list[str]
+
+
+# It comes back as a NEW version; nothing is deleted.
+class Rollback(WireModel):
+    """POST /v1/agents/{slug}/settings/rollback, the body: which version to bring back."""
+
+    version: int
+    team: bool = False
+
+
+# The org's lexicon: how the voice says the words it would get wrong, and the words the ears must
+# know. Shared by every agent of the org, laid over each one's own says and hears.
+class LexiconBody(WireModel):
+    """The org's lexicon."""
+
+    said: list[Pronunciation]
+    heard: list[str]
+
+
+class LexiconRow(WireModel):
+    """One kept version of the org's lexicon."""
+
+    holder: str
+    version: int
+    author: str
+    note: str | None
+    set_at: float
+    lexicon: LexiconBody
+
+
+# GET /v1/lexicon: the org's words as this key sees them — its own corner's, the team's and
+# production's, each corner's own newest, or null.
+class LexiconAnswer(WireModel):
+    """GET /v1/lexicon."""
+
+    world: Env
+    yours: LexiconRow | None
+    team: LexiconRow | None
+    production: LexiconRow | None
+
+
+# PUT /v1/lexicon, the body: the whole lexicon, the version it was read at, why, and whose corner.
+class LexiconPut(WireModel):
+    """PUT /v1/lexicon, the body."""
+
+    lexicon: LexiconBody
+    if_version: int | None = None
+    note: str | None = None
+    team: bool = False
+
+
+class LexiconHistory(WireModel):
+    """GET /v1/lexicon/history: one corner's versions, newest first."""
+
+    world: Env
+    holder: str
+    rows: list[LexiconRow]
+
+
+# GET /v1/calls/{call}/settings: the exact tuning and lexicon a call was built on, by the versions
+# its head row recorded.
+class CallTuning(WireModel):
+    """GET /v1/calls/{call}/settings."""
+
+    config_version: int | None
+    lexicon_version: int | None
+    config: TuningRow | None
+    lexicon: LexiconRow | None
+
+
+class KnowledgeFileRow(WireModel):
+    """One file of a base as the list draws it."""
+
+    path: str
+    chars: int
+    chunks: int
+    pushed_at: float
+
+
+# GET /v1/knowledge/{base}: every file of the base, by path, with its size and what it became. Never
+# the text: one file is read at a time.
+class KnowledgeFiles(WireModel):
+    """GET /v1/knowledge/{base}."""
+
+    base: str
+    kept: bool
+    files: list[KnowledgeFileRow]
+
+
+class KnowledgeFileRead(WireModel):
+    """GET /v1/knowledge/{base}/files/{path}: one file, text and all."""
+
+    path: str
+    text: str
+    chunks: int
+    pushed_at: float
+
+
+# New under that path, or replaced in place; the base is begun when there is none.
+class KnowledgeFilePut(WireModel):
+    """PUT /v1/knowledge/{base}/files/{path}, the body: the file's whole text."""
+
+    text: str
+
+
+# PUT /v1/knowledge/{base}/files/{path}, the answer: which file, how many chunks it became, and how
+# long that took.
+class KnowledgeFilePushed(WireModel):
+    """PUT /v1/knowledge/{base}/files/{path}, the answer."""
+
+    base: str
+    path: str
+    chunks: int
+    took_ms: float
+
+
+class KnowledgeUse(WireModel):
+    """One base and the agents whose settings attach it."""
+
+    base: str
+    agents: list[str]
+
+
+# GET /v1/knowledge/attached: which agents read each base, off every agent's newest settings in this
+# world.
+class KnowledgeUses(WireModel):
+    """GET /v1/knowledge/attached."""
+
+    bases: list[KnowledgeUse]
+
+
+# One synthetic caller of an ORG, kept by the gateway: what they want, how they talk, and what they
+# may state about themselves. A model plays them turn by turn — there is no script — for `pinecall
+# simulate` and the console's Simulations. A caller is a person on the phone, so who they are does
+# not depend on which of the org's agents answers: every agent of the org calls with the same list.
+class Persona(WireModel):
+    """One synthetic caller of an ORG, kept by the gateway."""
+
+    name: str
+    about: str
+    goal: str
+    style: str
+    facts: dict[str, str]
+    state: dict[str, Any]
+    llm: str | None
+    tts: str | None
+    voice: str | None
+    accepts_when: str
+    declines_when: str
+    author: str
+    set_at: float
+
+
+# The same list for every agent of the org, and the same one in both worlds.
+class PersonaList(WireModel):
+    """GET /v1/personas: every caller the org wrote, by name."""
+
+    personas: list[Persona]
+
+
+# A name that exists is replaced; `was` renames the caller it names.
+class PersonaPut(WireModel):
+    """PUT /v1/personas/{name}, the body: the caller, written whole."""
+
+    about: str | None = None
+    goal: str
+    style: str
+    facts: dict[str, str] | None = None
+    state: dict[str, Any] | None = None
+    llm: str | None = None
+    tts: str | None = None
+    voice: str | None = None
+    accepts_when: str | None = None
+    declines_when: str | None = None
+    was: str | None = None
+
+
+# Read off the call index, never off a log — the same row the sessions list is drawn from.
+class PersonaRun(WireModel):
+    """One simulation this caller has run: the call it was, and what the call came to."""
+
+    call: str
+    agent: str
+    started_at: float
+    ended_at: float | None
+    turns: int
+    end_reason: EndReason | None
+    outcome: str | None
+    cost_eur: float | None
+    score: SessionScore | None
+
+
+# GET /v1/personas/{name}/runs, in the key's own world and corner, paged exactly as the sessions
+# list is.
+class PersonaRunList(WireModel):
+    """Every simulation this caller has run, newest first, a page at a time."""
+
+    runs: list[PersonaRun]
+    total: int
+    next: str | None
+
+
+# One voice a picker offers, as GET /v1/voices lists it: the id the `voice` setting takes, and what
+# a person chooses by. `country` and `accent` are the vendor's own words (`ES` is Spain, `MX`
+# Mexico), empty when the vendor said none.
+class ListedVoice(WireModel):
+    """One voice a picker offers, as GET /v1/voices lists it."""
+
+    id: str
+    name: str
+    language: str
+    description: str
+    gender: str
+    country: str
+    accent: str
+
+
+# GET /v1/voices?tts=&language=: a voice vendor's own voices in one language, in the vendor's order.
+class VoicesListed(WireModel):
+    """GET /v1/voices?tts=&language=."""
+
+    tts: str
+    language: str | None
+    voices: list[ListedVoice]
+
+
+# POST /v1/voices/sample, the body: which vendor, which voice, which model and which words to hear.
+# The answer is the WAV itself (`audio/wav`), with `Server-Timing: first-audio;dur=…, total;dur=…`
+# in milliseconds.
+class VoiceSample(WireModel):
+    """POST /v1/voices/sample, the body."""
+
+    tts: str
+    voice: str
+    model: str | None = None
+    language: str | None = None
+    text: str | None = None

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/state.py

@@ -134,11 +134,22 @@ class TransferState(WireModel):
     """The transfer in flight or the one that happened."""
 
     to: str
-    mode: TransferMode
+    mode: TransferMode | None = None
     status: Literal["requested", "done", "failed"]
     by: Literal["agent", "supervisor"]
 
 
+# The agent's last ask for a person, from attention.requested until attention.answered settles it.
+class AttentionState(WireModel):
+    """AttentionState, as protocol/schema declares it."""
+
+    reason: str
+    wait_s: float
+    status: Literal["open", "answered", "lapsed"]
+    asked_at: float
+    by: Supervisor | None
+
+
 class LiveTranscript(WireModel):
     """The words on screen right now: interim transcripts that a finished turn clears."""
 
@@ -233,6 +244,7 @@ class State(WireModel):
     held: bool
     muted: bool
     transfer: TransferState | None
+    attention: AttentionState | None = None
     usage: list[ModelUsage]
     cost: Cost | None
     routes: list[Route]

{pinecall_protocol-0.3.0 → pinecall_protocol-0.6.14}/pinecall_protocol/verbs.py

@@ -45,12 +45,13 @@ class TransferVerb(WireModel):
 
     verb: Literal["transfer"] = "transfer"
     to: str
-    mode: TransferMode
+    mode: TransferMode | None = None
 
 
-# Logged as supervisor.ended, then call.ended with reason supervisor_ended.
+# Hang up on the caller's behalf, at once: a sentence playing and a reply still being written are
+# cut, not finished. Logged as supervisor.ended, then call.ended with reason supervisor_ended.
 class EndVerb(WireModel):
-    """Hang up on the caller's behalf."""
+    """Hang up on the caller's behalf, at once."""
 
     verb: Literal["end"] = "end"
     reason: str | None = None

pinecall_protocol-0.3.0/pinecall_protocol/_version.py

@@ -1,4 +0,0 @@
-"""The one place the version lives; hatch reads it from here at build time."""
-
-# 0.0.0 means "unreleased". The number is the maintainer's call and is never bumped from code.
-__version__ = "0.3.0"