meeting

type Agent struct {
	Name    string
	Voice   string
	Execute Execute
	// Model labels the model this agent's turns run on (its `model:` when
	// configured in the session, else the session model); status shows it.
	Model string
	// Note explains a fallback (e.g. an unconfigured `model:`); shown on attach.
	Note string
}

type AuditEntry struct {
	Time    time.Time `json:"time"`
	Meeting string    `json:"meeting,omitempty"` // Recall bot id
	// MeetingID is the registry id (m-xxxxxx, design 043) of the meeting
	// the turn ran in.
	MeetingID string `json:"meeting_id,omitempty"`
	Turn      string `json:"turn"`
	Agent     string `json:"agent"`
	Speaker   string `json:"speaker"` // display name: a label, not authentication
	Tool      string `json:"tool"`
	Target    string `json:"target,omitempty"` // redacted, ≤ 160 runes
	Status    string `json:"status"`           // started | ok | error | blocked_by_policy | incomplete (started, never ended: the turn stopped first)
}

type Command struct {
	Action string `json:"action"`
	// ID names the meeting (m-xxxxxx, design 043); "" = the only meeting with
	// a bot, else the only meeting. join/host without it create a meeting.
	ID        string `json:"id,omitempty"`
	URL       string `json:"url,omitempty"`
	PublicURL string `json:"public_url,omitempty"`
	Listen    string `json:"listen,omitempty"`
	Region    string `json:"region,omitempty"`
	ReadDir   string `json:"read_dir,omitempty"`
	TTS       string `json:"tts,omitempty"`  // openai | deepgram | elevenlabs (design 048)
	STT       string `json:"stt,omitempty"`  // deepgram | elevenlabs; rysh rooms only (Recall transcribes itself)
	Lang      string `json:"lang,omitempty"` // ISO 639 code the agents answer and speak in; "" = English (design 048)
	Consent   bool   `json:"consent,omitempty"`
	// KeepTranscript keeps a reporter's raw transcript on disk for this
	// meeting (H-61, 045 D5; off by default). It needs TranscriptConsent:
	// the reporter's own Consent does not cover it.
	KeepTranscript    bool `json:"keep_transcript,omitempty"`
	TranscriptConsent bool `json:"transcript_consent,omitempty"`
	AutoSpeak         bool `json:"auto_speak,omitempty"`
	// Approve restores per-turn local approval (approve, then speak). Without
	// it the bot is hands-free: an allowed speaker's request runs and the
	// reply is spoken with no terminal input (founder decision 2026-09-27).
	Approve bool `json:"approve,omitempty"`
	// Allow lists who may wake the bot: display names and/or the keywords
	// "host" and "anyone". Empty means "host". Names are labels the
	// participant chose, not authentication.
	Allow []string `json:"allow,omitempty"`
	// AllowFromFlag marks an Allow the operator typed on `##meeting add
	// agent`; an attach refuses it (the allowlist is fixed at bot start).
	// Set by the daemon, never taken from a client.
	AllowFromFlag bool   `json:"-"`
	Minutes       int    `json:"minutes,omitempty"`
	TurnID        string `json:"turn_id,omitempty"`
	// Agents names ##agent-spawned agents to attach at join ("hey <name>");
	// the first one also answers "hey rysh". Agent is the attach/detach target.
	Agents []string `json:"agents,omitempty"`
	Agent  string   `json:"agent,omitempty"`
	// Model labels the session model plain "hey rysh" turns run on. Set by the
	// daemon at join, never taken from a client.
	Model string `json:"-"`
	// AuditPath is the JSONL file meeting tool calls are appended to
	// (audit.go). Set by the daemon under the session dir, never by a client.
	AuditPath string `json:"-"`
	// ZoomOBF gives Recall a zoom.obf_token_url on this listener so a Zoom
	// meeting hosted by another account can be joined on behalf of an
	// authorised Zoom user (zoomobf.go). Off by default.
	ZoomOBF bool `json:"zoom_obf,omitempty"`
	// Room names the LiveKit room `host` creates; "" = a random rysh-… name.
	Room string `json:"room,omitempty"`
	// Server, for host, is a rysh-server base URL: the room, the bot token
	// and the invite come from it instead of local LiveKit signing.
	Server string `json:"server,omitempty"`
	// PaneID is the meeting pane a `register` binds (##meeting join). Set by
	// the daemon, never taken from a client.
	PaneID string `json:"-"`
	// Reporter commands (design 045), all set by the daemon: ReportDir is
	// the meeting's report directory (<rysh dir>/meetings/<id>), Origin the
	// pane told when the report is written, Session the session's name.
	ReportDir string `json:"-"`
	Origin    string `json:"-"`
	Session   string `json:"-"`
	// contains filtered or unexported fields
}

type Credentials struct {
	Recall, Verification, Speech string
	Zoom                         ZoomCredentials    // only with --zoom-obf
	LiveKit                      LiveKitCredentials // only for host
	RyshAPIKey                   string             // host --server: rysh API key with write
	// UpstreamAPIKey reports (doctor only) that the session has an
	// upstream.api_key, which host --server uses when RYSH_API_KEY is unset.
	UpstreamAPIKey bool
}

type Execute func(context.Context, string) (string, error)

type Invite struct {
	ID            string `json:"id"`
	TokenPrefix   string `json:"token_prefix"`
	Label         string `json:"label"`
	GuestName     string `json:"guest_name"`
	AllowGuest    bool   `json:"allow_guest"`
	MaxUses       int    `json:"max_uses"`
	Uses          int    `json:"uses"`
	ExpiresAt     string `json:"expires_at"`
	RevokedAt     string `json:"revoked_at,omitempty"`
	LastUsedAt    string `json:"last_used_at,omitempty"`
	JoinURL       string `json:"-"`
	GuestIdentity string `json:"-"`
}

type InviteRequest struct {
	Email string        // personal invite labelled with this address
	Guest bool          // personal invite without an address
	Name  string        // the guest's default display name
	TTL   time.Duration // 0 = the server's default (24 h, never past the room)
}

type LiveKitConfig struct {
	URL       string // ws(s):// signalling URL
	APIKey    string
	APISecret string
	Room      string
}

type LiveKitCredentials struct {
	URL, APIKey, APISecret string
	JoinPage               string // "" = defaultJoinPage
	STTKey                 string // STTKeyName(Command.STT): per-participant streaming STT
}

type LiveKitDialOptions struct {
	STT, Lang, STTKey string
	// Keyterms is the bot's current agent names, read by the transcriber
	// to bias recognition towards them (E-85); nil = only "Rysh".
	Keyterms func() []string
}

type LiveKitEvent struct {
	Kind       string
	Identity   string
	Name       string
	Text       string
	Start, End float64
}

type LiveKitProbe struct {
	// contains filtered or unexported fields
}

type LiveKitRoom interface {
	// Events delivers final utterances and participant/connection changes;
	// it is closed when the connection ends.
	Events() <-chan LiveKitEvent
	// Play publishes one reply on the bot's audio track and returns when it
	// has been sent, or when ctx is cancelled (barge-in, stop). audio is what
	// the Service's speech produced: LiveKitSpeech's format when set (LK-1
	// uses Ogg/Opus), else the MP3 of the Recall route.
	Play(ctx context.Context, audio []byte) error
	Close() error
}

type Manager struct {
	// contains filtered or unexported fields
}

type Meeting struct {
	ID       string // m-xxxxxx
	Kind     string // KindWeb | KindLiveKit
	Platform string // PlatformMeet | PlatformZoom | PlatformTeams | PlatformLiveKit
	Target   string // meeting URL (web) or room id (livekit)
	Server   string // rysh-server base (livekit rooms)
	PaneID   string // "" for pane-less CLI meetings
	// Bots are the meeting's bots in start order: one per agent for
	// `##meeting add agent` (D9), or the one bot of a CLI join/host, which
	// may carry several attached agents.
	Bots      []*Service
	CreatedAt time.Time

	// Reporter is the meeting's listen-only reporter bot (design 045), kept
	// apart from Bots: it answers no wake, is not an agent and does not
	// count toward MaxAgentBots. lastReport is the newest report written.
	Reporter *Service
	// contains filtered or unexported fields
}

type OpusSpeech func(ctx context.Context, text string) ([]byte, error)

type ParticipantGrant struct {
	URL       string `json:"url"`
	Token     string `json:"token"`
	Identity  string `json:"identity"`
	ExpiresAt string `json:"expires_at"`
}

type Reply struct {
	ID             string          `json:"id,omitempty"`       // meeting id (m-xxxxxx)
	Kind           string          `json:"kind,omitempty"`     // "web" | "livekit"
	PaneID         string          `json:"pane_id,omitempty"`  // meeting pane; "" = pane-less
	Target         string          `json:"target,omitempty"`   // meeting URL (web) or room id (livekit)
	Meetings       []Reply         `json:"meetings,omitempty"` // list
	Bots           []Reply         `json:"bots,omitempty"`     // one status per bot of the meeting (D9), in start order
	State          string          `json:"state"`
	Platform       string          `json:"platform,omitempty"`
	BotID          string          `json:"bot_id,omitempty"`
	TurnID         string          `json:"turn_id,omitempty"`
	Speaker        string          `json:"speaker,omitempty"`
	Request        string          `json:"request,omitempty"` // explicit local `pending` only
	Result         string          `json:"result,omitempty"`  // explicit local `pending` only
	Error          string          `json:"error,omitempty"`
	Notice         string          `json:"notice,omitempty"`
	Phase          string          `json:"phase,omitempty"` // status-wall vocabulary, see Phase
	Mode           string          `json:"mode,omitempty"`  // "hands_free" or "approve"
	MediaConnected bool            `json:"media_connected"`
	SegmentsHeard  int             `json:"segments_heard,omitempty"`
	IgnoredWakes   int             `json:"ignored_wakes,omitempty"` // wakes from speakers outside the allowlist
	Allow          []string        `json:"allow,omitempty"`         // who may wake the bot in this meeting: display names, "host", "anyone"
	Secrets        map[string]bool `json:"secrets,omitempty"`
	Agent          string          `json:"agent,omitempty"`       // agent addressed by the pending turn; "" = rysh
	Agents         []string        `json:"agents,omitempty"`      // agents attached to this meeting
	Voices         []string        `json:"voices,omitempty"`      // each attached agent's TTS voice, in Agents order ("" = provider default)
	Model          string          `json:"model,omitempty"`       // model answering the pending turn
	ToolCalls      int             `json:"tool_calls"`            // audited tool calls from meeting turns
	AuditLog       string          `json:"audit_log,omitempty"`   // file holding those entries
	Room           string          `json:"room,omitempty"`        // LiveKit room (`host`)
	JoinURL        string          `json:"join_url,omitempty"`    // link for people to join that room (`host` reply only)
	Report         *ReportStatus   `json:"report,omitempty"`      // the meeting's reporter (design 045)
	LastReport     string          `json:"last_report,omitempty"` // the newest report written for this meeting
}

type ReportAssignment struct {
	Who  string `json:"who,omitempty"`
	What string `json:"what"`
	When string `json:"when,omitempty"`
}

type ReportConfig struct {
	MeetingID, PaneID, Origin string
	Platform, Session         string
	Dir                       string
	Summarize                 Execute
	OnEvent                   func(ReportEvent)
	KeepTranscript            bool // H-61: also append the raw transcript to TranscriptFile
}

type ReportEvent struct {
	MeetingID, PaneID, Origin string
	Path                      string
	Interim                   bool
	Error                     string
	Summary                   string // one line for the notice: counts per section
}

type ReportItem struct {
	Owner  string `json:"owner,omitempty"`
	Item   string `json:"item"`
	Status string `json:"status,omitempty"`
}

type ReportNotes struct {
	Overview      string             `json:"overview,omitempty"`
	Topics        []ReportTopic      `json:"topics,omitempty"`
	PreviousItems []ReportItem       `json:"previous_items,omitempty"`
	Blockers      []ReportItem       `json:"blockers,omitempty"`
	Plan          []string           `json:"plan,omitempty"`
	Assignments   []ReportAssignment `json:"assignments,omitempty"`
	Decisions     []string           `json:"decisions,omitempty"`
}

type ReportStatus struct {
	State        string   `json:"state"`                  // listening | summarizing | writing | written | failed
	BotState     string   `json:"bot_state,omitempty"`    // the reporter bot's state (joining, listening, ended, …)
	Segments     int      `json:"segments"`               // transcript segments heard (count only)
	Chunks       int      `json:"chunks"`                 // chunks summarized so far
	Buffered     int      `json:"buffered_chars"`         // transcript in memory awaiting its summary
	Participants []string `json:"participants,omitempty"` // speakers heard, by display name
	Path         string   `json:"path,omitempty"`         // report.md once written (interim or final)
	Interim      bool     `json:"interim,omitempty"`      // Path holds an interim report
	Transcript   string   `json:"transcript,omitempty"`   // the kept raw transcript (H-61 opt-in); "" = not kept
	Error        string   `json:"error,omitempty"`
}

type ReportTopic struct {
	Title   string `json:"title"`
	Summary string `json:"summary,omitempty"`
}

type RoomRef struct {
	Server string // rysh-server base, e.g. https://rysh.ai
	Room   string // room id
	// ExpiresAt is when the room ends (RFC 3339), set by CreateRoom only.
	ExpiresAt string
}

type Segment struct {
	Participant int     // stable per participant for this meeting
	Name        string  // display label; never authority by itself
	Identity    string  // authenticated identity (LiveKit token); "" on Recall
	Host        bool    // the platform/room says this participant is the host
	Start, End  float64 // seconds, relative to the meeting's own clock
	Words       []string
}

type Service struct {
	// contains filtered or unexported fields
}

type Synthesize func(context.Context, string) ([]byte, error)

type SynthesizeStream func(context.Context, string) (io.ReadCloser, error)

type Transcriber func(ctx context.Context, audio <-chan []byte, emit func(text string)) error

type Transport interface {
	// Kind names the backbone: "recall" or "livekit".
	Kind() string
	// Join puts the bot into the meeting and returns its id. A *joinError
	// says whether a failure is definite (nothing was created) or uncertain.
	Join(ctx context.Context) (id string, err error)
	// Leave removes the bot. A *leaveError carries the operator notice.
	Leave(ctx context.Context) error
	// Status reports admission/end; an error is a status outage whose text
	// is the pause notice.
	Status(ctx context.Context) (TransportStatus, error)
	// MediaReadyLocked reports whether audio can be delivered to the meeting.
	MediaReadyLocked() bool
	// SpeakLocked starts playing one reply; completion is reported through
	// Service.playbackLocked(turnID, ok). An error means delivery never
	// started.
	SpeakLocked(turnID string, audio []byte) error
	// ClearLocked stops any playback in progress.
	ClearLocked()
}

type TransportStatus struct {
	Unknown  bool   // nothing to report yet; leave state as it is
	Admitted bool   // the bot is in the call and hears participants
	Ended    bool   // the meeting ended or the bot was removed
	Why      string // with Ended: the provider's reason, when it gave one
	Waiting  string // while joining: the host action the bot waits for
	Lost     string // after joining: why hearing stopped
}

type ZoomCredentials struct {
	ClientID, ClientSecret, RefreshToken string
	SaveRefresh                          func(string) error
}