Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
"""Session interaction wire contract, version 1.
A Python mirror of `console/packages/shared/src/session-v1/contract.ts` and its
zod schemas in `validation.ts`. The TypeScript side is the original; this is a
second reading of the same wire format for the half of Switch that is written
in Python, and the two only stay in step deliberately. A divergence does not
fail on either side of the wire on its own — it just renders the wrong thing,
or rejects a message the other end considers valid.
`test_session_contract_parity.py` reads the same `examples.json` as
`session-v1.test.ts` and asserts the shapes that test asserts, so the pair fails
loudly when one moves.
Field names on the wire are camelCase; the models accept and emit those, and
expose snake_case attributes. Dump with `by_alias=True`.
"""
from __future__ import annotations
import json
from datetime import datetime
from typing import Annotated, Any, Literal
from pydantic import (
AfterValidator,
BaseModel,
ConfigDict,
Field,
StringConstraints,
)
from pydantic.alias_generators import to_camel
# The contract is carried by JSON, so a counter has to survive a double. The
# TypeScript side bounds every counter by Number.MAX_SAFE_INTEGER; a Python int
# does not overflow there, which is exactly why the bound has to be explicit.
MAX_SAFE_INTEGER = 9007199254740991
# `parseHostEvent` refuses anything larger. Hosts split before they send.
MAX_EVENT_BYTES = 64 * 1024
def _iso_datetime(value: str) -> str:
"""Reject a timestamp zod's `z.iso.datetime()` would reject."""
try:
datetime.fromisoformat(value.replace("Z", "+00:00"))
except ValueError as error:
raise ValueError(f"not an ISO-8601 timestamp: {value!r}") from error
return value
Id = Annotated[str, StringConstraints(min_length=1)]
Counter = Annotated[int, Field(ge=0, le=MAX_SAFE_INTEGER)]
Sequence = Annotated[int, Field(ge=1, le=MAX_SAFE_INTEGER)]
Timestamp = Annotated[str, AfterValidator(_iso_datetime)]
# Where something was done: Switch's own two surfaces, or a messaging platform
# by its key. Any platform key is accepted rather than a fixed list, so a newly
# registered platform's frames validate without a contract change; the pattern
# is `messaging_platforms.PLATFORM_KEY_PATTERN`, written out because the
# contract is mirrored in TypeScript and must not depend on the bridge layer.
Surface = Annotated[
str, StringConstraints(pattern=r"^(console|switch-web|[a-z][a-z0-9_]{1,31})$")
]
Provider = Annotated[str, StringConstraints(min_length=1)]
class _Model(BaseModel):
"""Every contract type: camelCase on the wire, unknown keys refused.
Refusing unknown keys is the point rather than a default. The contract
carries no provider-native payload, and a bridge that silently forwarded one
would publish whatever a host chose to attach into a room.
"""
model_config = ConfigDict(
alias_generator=to_camel,
populate_by_name=True,
extra="forbid",
frozen=True,
protected_namespaces=(),
)
class Origin(_Model):
"""Who acted, and where. The server sets this from a verified identity."""
surface: Surface
actor_id: Id
room_id: Id | None
thread_id: Id | None
message_id: Id | None
class Capability(_Model):
input: Literal["queue", "steer"]
approvals: bool
questions: bool
interrupt: bool
reset: bool
compact: bool
model_change: bool
attachment_mime_types: list[str]
# Absent from a host built before `message.retry`, which means it cannot.
retry: bool = False
class Attachment(_Model):
attachment_id: Id
name: str
mime_type: str
bytes: Counter
sha256: str | None = None
class Item(_Model):
item_id: Id
turn_id: Id
revision: Counter
kind: Literal["user-message", "assistant-message", "tool-activity"]
status: Literal["in-progress", "completed", "failed", "declined"]
title: str
text: str
attachments: list[Attachment]
origin: Origin | None
class ApprovalOption(_Model):
option_id: Id
label: str
decision: Literal["accept", "acceptForSession", "decline", "cancel"]
class QuestionOption(_Model):
option_id: Id
label: str
description: str | None
class Question(_Model):
question_id: Id
title: str
prompt: str
options: list[QuestionOption]
multi_select: bool
allow_custom_answer: bool
class Answer(_Model):
question_id: Id
selected_option_ids: list[Id]
custom_text: str | None
class ApprovalResult(_Model):
kind: Literal["approval"]
option_id: Id
class QuestionsResult(_Model):
kind: Literal["questions"]
answers: list[Answer]
RequestResult = Annotated[
ApprovalResult | QuestionsResult,
Field(discriminator="kind"),
]
class ApprovalContent(_Model):
kind: Literal["approval"]
title: str
detail: str | None
options: list[ApprovalOption]
class QuestionsContent(_Model):
kind: Literal["questions"]
title: str
questions: list[Question]
RequestContent = Annotated[
ApprovalContent | QuestionsContent,
Field(discriminator="kind"),
]
class Request(_Model):
request_id: Id
turn_id: Id
revision: Counter
state: Literal["open", "submitting", "resolved", "closed"]
content: RequestContent
expires_at: Timestamp | None
class SessionModel(_Model):
id: Id
options: dict[str, str]
class SessionContext(_Model):
used_tokens: int = Field(ge=0)
window_tokens: int | None = Field(gt=0)
updated_at: Timestamp
class ModelChoice(_Model):
id: Id
label: str
options: dict[str, list[str]]
image_input: bool | None = None
class Session(_Model):
room_ids: list[Id] = Field(default_factory=list)
retired: bool = False
session_id: Id
agent_id: Id
provider: Provider
host_id: Id
epoch: Id
status: Literal["starting", "ready", "running", "stopped", "error"]
connectivity: Literal["online", "offline"]
capabilities: Capability
pending_request_ids: list[Id]
models: list[ModelChoice] = Field(default_factory=list)
model: SessionModel | None = None
context: SessionContext | None = None
# ── Event bodies ─────────────────────────────────────────────────────────────
class UnavailableSession(_Model):
session_id: Id
agent_id: Id
discovery_error: str
class SessionUpsert(_Model):
type: Literal["session.upsert"]
session: Session
class TurnUpsert(_Model):
type: Literal["turn.upsert"]
turn_id: Id
status: Literal["queued", "running", "completed", "interrupted", "error"]
command_id: Id | None
TURN_ENDED = frozenset({"completed", "interrupted", "error"})
class ItemUpsert(_Model):
type: Literal["item.upsert"]
item: Item
class RequestOpened(_Model):
type: Literal["request.opened"]
request: Request
class RequestSettled(_Model):
type: Literal["request.settled"]
request_id: Id
revision: Counter
outcome: Literal[
"answered", "cancelled", "expired", "interrupted", "provider-error"
]
command_id: Id | None
result: RequestResult | None
class CommandResult(_Model):
type: Literal["command.result"]
command_id: Id
status: Literal["applied", "rejected", "unknown"]
code: str | None
message: str | None
class Notice(_Model):
type: Literal["notice"]
level: Literal["info", "warning", "error"]
code: Id
message: str
class CommandStatus(_Model):
type: Literal["command.status"]
command_id: Id
status: Literal["accepted", "dispatched", "applied", "rejected", "unknown"]
code: str | None
message: str | None
class RequestSubmitting(_Model):
type: Literal["request.submitting"]
request_id: Id
revision: Counter
command_id: Id
actor_id: Id
surface: Surface
class SessionConnectivity(_Model):
type: Literal["session.connectivity"]
connectivity: Literal["online", "offline"]
_HostBodies = (
SessionUpsert
| TurnUpsert
| ItemUpsert
| RequestOpened
| RequestSettled
| CommandResult
| Notice
)
HostBody = Annotated[_HostBodies, Field(discriminator="type")]
ServerBody = Annotated[
_HostBodies | CommandStatus | RequestSubmitting | SessionConnectivity,
Field(discriminator="type"),
]
class HostEvent(_Model):
contract_version: Literal[1]
event_id: Id
session_id: Id
epoch: Id
host_sequence: Sequence
occurred_at: Timestamp
body: HostBody
class ServerEvent(_Model):
contract_version: Literal[1]
event_id: Id
session_id: Id
sequence: Sequence
occurred_at: Timestamp
body: ServerBody
# ── Commands ─────────────────────────────────────────────────────────────────
class MessageSend(_Model):
type: Literal["message.send"]
text: str
attachments: list[Attachment]
delivery: Literal["queue", "steer"]
class RequestAnswer(_Model):
type: Literal["request.answer"]
request_id: Id
expected_revision: Counter
answer: RequestResult
class TurnInterrupt(_Model):
type: Literal["turn.interrupt"]
turn_id: Id
class SessionStop(_Model):
type: Literal["session.stop"]
class SessionReset(_Model):
type: Literal["session.reset"]
class SessionCompact(_Model):
type: Literal["session.compact"]
class MessageRetry(_Model):
"""Run again the turn a room message started, which ended without an answer."""
type: Literal["message.retry"]
message_id: Id
class SessionModelSet(_Model):
type: Literal["session.model.set"]
model_id: Id
options: dict[str, str]
CommandBody = Annotated[
MessageSend
| RequestAnswer
| TurnInterrupt
| SessionStop
| SessionReset
| SessionCompact
| MessageRetry
| SessionModelSet,
Field(discriminator="type"),
]
class Command(_Model):
"""The server sets origin from a verified identity. A client body has none."""
contract_version: Literal[1]
command_id: Id
session_id: Id
epoch: Id
origin: Origin
body: CommandBody
class RoomMessageReceipt(CommandStatus):
"""A room-message receipt for a host that asked to be handed the command.
The command is set only when this submission is what created it and the
session has nothing else queued, so running it from here cannot put it
ahead of work asked for earlier. Any other status is a receipt to report
rather than work to run, and the command endpoint remains the way to reach
one withheld here or lost with this response.
"""
command: Command | None
# ── Snapshot ─────────────────────────────────────────────────────────────────
class DecidedBy(_Model):
actor_id: Id
surface: Surface
command_id: Id
class SnapshotRequest(Request):
"""A request as the snapshot carries it: with how, and by whom, it settled."""
result: RequestSettled | None
decided_by: DecidedBy | None
class Snapshot(_Model):
contract_version: Literal[1]
through_sequence: Counter
session: Session
turns: list[TurnUpsert]
items: list[Item]
requests: list[SnapshotRequest]
command_statuses: list[CommandStatus]
next_page_token: str | None
# ── Parsing ──────────────────────────────────────────────────────────────────
def event_bytes(event: Any) -> int:
"""The size the host measured.
The host counts `TextEncoder().encode(JSON.stringify(event)).byteLength`, so
both of `json.dumps`'s defaults have to go: it pads every separator, and it
escapes anything non-ASCII, which makes an emoji twelve bytes here and four
on the host. Either one alone reads a compliant event as oversized.
"""
return len(
json.dumps(event, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
)
def parse_host_event(payload: Any) -> HostEvent:
"""Read a host event, refusing one no host should have sent."""
if event_bytes(payload) > MAX_EVENT_BYTES:
raise ValueError("PAYLOAD_TOO_LARGE: event exceeds 64 KiB.")
event = HostEvent.model_validate(payload)
body = event.body
if isinstance(body, SessionUpsert) and (
body.session.session_id != event.session_id or body.session.epoch != event.epoch
):
raise ValueError("Session identity does not match event envelope.")
return event
def parse_server_event(payload: Any) -> ServerEvent:
return ServerEvent.model_validate(payload)
def parse_snapshot(payload: Any) -> Snapshot:
return Snapshot.model_validate(payload)
def parse_command(payload: Any) -> Command:
return Command.model_validate(payload)
# The decisions that answer the question a permission card asks: yes for this
# turn, yes for the session, and no. `cancel` is left out — it stops the
# operation rather than deciding it, and its card is the channel's only record
# that a run was halted where it was. Named once so that a fifth value added to
# `ApprovalOption.decision` has to be considered here.
DECISIONS = frozenset({"accept", "acceptForSession", "decline"})
def decided(request: SnapshotRequest) -> bool:
"""Whether the host confirmed that a person answered this card.
Not "has it finished". `answered` is equally the outcome of a request that
ended without anyone reading it, and `resolved` equally its state; what
this asks is narrower. It deliberately does not ask which *way* the answer
went: a yes and a no both end the card's usefulness, because the decision
is in the session, in Console and in the row, not in a message still
offering buttons that no longer do anything.
Reaching that fact means matching the result back to the options the
request was asked with, and everything short of the match is read as
undecided, because the caller acts on it irreversibly. An answer naming an
option the request never offered, an approval settled with no result at
all, a questions result on an approval: each is a host saying something
this cannot interpret, and an unreadable answer leaves a card a person can
read by hand.
"""
if request.state != "resolved":
return False
settled = request.result
if settled is None or settled.outcome != "answered":
return False
answer = settled.result
content = request.content
if not isinstance(answer, ApprovalResult) or not isinstance(
content, ApprovalContent
):
return False
return any(
option.option_id == answer.option_id and option.decision in DECISIONS
for option in content.options
)