attention

type AttentionItem struct {
	ID        string    `json:"id"`         // stable attention-item id (att_%d)
	Priority  Priority  `json:"priority"`   // P0..P3
	Kind      Kind      `json:"kind"`       // ask | permission | error | ...
	SessionID string    `json:"session_id"` // origin session
	Alias     string    `json:"alias"`      // pronounceable session name for speech
	Spoken    string    `json:"spoken"`     // text written for the ear
	State     ItemState `json:"state"`
	CreatedAt time.Time `json:"created_at"`

	// RefID is moa's real pending id for P0 ask/permission (perm_%d / ask_%d),
	// empty for errors. The client resolves via existing /ask & /permission
	// endpoints; resolution flows back through the bus, not through this service.
	RefID string `json:"ref_id,omitempty"`

	// Risk metadata — only meaningful for KindPermission. Populated by the
	// deterministic risk parser (assessRisk). Never softened by any model.
	RiskLevel RiskLevel `json:"risk_level,omitempty"`
	RiskFlags []string  `json:"risk_flags,omitempty"`
	// Verbatim is the exact command/args, ALWAYS captured even when not read
	// aloud, so a client can offer "read it to me literally".
	Verbatim string `json:"verbatim,omitempty"`
}

type Briefing struct {
	Priority  Priority `json:"priority"`   // P1 (terminal) or P2 (progress)
	Kind      Kind     `json:"kind"`       // run_ok | goal_ended | goal_stalled | verify_fail
	SessionID string   `json:"session_id"` // origin session
	Alias     string   `json:"alias"`      // pronounceable session name
	Spoken    string   `json:"spoken"`     // text written for the ear

	// Termination is set only for a successful run completion. It lets a voice
	// client ask for the full result through the existing messages endpoint.
	Termination *RunTermination `json:"termination,omitempty"`
}

type ClientMsg struct {
	Type          string `json:"type"`           // "ack" | "ack_termination" | "get_status"
	RequestID     string `json:"request_id"`     // echoed on errors
	ItemID        string `json:"item_id"`        // for ack
	TerminationID string `json:"termination_id"` // for ack_termination
}

type ClientSink interface {
	// Send delivers one server->client message. Returns false if the sink is
	// dead (the loop then forgets it).
	Send(msg ServerMsg) bool
	// ID identifies the connection so the loop can detect supersession.
	ID() uint64
	// Close revokes this sink. A superseded guardian must not retain a live
	// control channel.
	Close()
}

type Config struct {
	// Lang is the resolved briefing language code (e.g. "en", "es"); from
	// core.GetSTTLanguage. Empty -> English.
	Lang string

	// OnUndelivered is an optional future push hook. It is called when a P0
	// item is born without an active guardian; callers can use it to wake a
	// paired phone without putting APNs policy in this package.
	OnUndelivered func(AttentionItem)
}

type ItemState string

type Kind string

type Priority int

type RiskLevel string

type RunTermination struct {
	ID        string         `json:"id"`
	SessionID string         `json:"session_id"`
	Alias     string         `json:"alias"`
	Spoken    string         `json:"spoken"`
	Summary   string         `json:"summary"`
	CreatedAt time.Time      `json:"created_at"`
	Ref       TerminationRef `json:"ref"`
}

type ServerMsg struct {
	Type string `json:"type"` // "init" | "attention" | "item_update" | "briefing" | "roster" | "inactive" | "error"
	V    int    `json:"v,omitempty"`

	// init
	Items    []AttentionItem `json:"items,omitempty"`    // all unresolved P0 items
	Sessions []SessionBrief  `json:"sessions,omitempty"` // the roster of attached sessions (init + roster)

	// attention (a new item) / item_update (state change of an existing item)
	Item *AttentionItem `json:"item,omitempty"`

	// briefing: an ephemeral progress/terminal note. It is NOT
	// tracked or resolvable. The sole exception is a successful run completion,
	// whose Termination metadata is retained for recovery in init.
	Briefing *Briefing `json:"briefing,omitempty"`

	// terminations contains successful run completions awaiting explicit client
	// acknowledgement. It appears only in init and is replaced by the next init,
	// like Items and Sessions. Clients must deduplicate by ID and send
	// ack_termination only after speaking the notice.
	Terminations []RunTermination `json:"terminations,omitempty"`

	// error
	RequestID string `json:"request_id,omitempty"`
	Code      string `json:"code,omitempty"`
	Message   string `json:"message,omitempty"`
}

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

type SessionActivity struct {
	Kind   string `json:"kind"`             // "subagent" | "tool"
	Detail string `json:"detail,omitempty"` // subagent task, or tool target (bash command, etc.), bounded
	Tool   string `json:"tool,omitempty"`   // tool name when kind=="tool" (bash, edit, fetch_content, ...)
	Model  string `json:"model,omitempty"`  // child model when kind=="subagent"
	Count  int    `json:"count,omitempty"`  // number of active subagents when kind=="subagent"
}

type SessionBrief struct {
	SessionID    string           `json:"session_id"`
	Alias        string           `json:"alias"`
	Title        string           `json:"title"`
	State        string           `json:"state"`         // idle | running | permission | error
	PendingAsks  int              `json:"pending_asks"`  // count of unanswered questions
	PendingPerm  int              `json:"pending_perms"` // count of unresolved permissions
	Activity     *SessionActivity `json:"activity,omitempty"`
	Attempting   string           `json:"brief_attempting,omitempty"`
	Progress     string           `json:"brief_progress,omitempty"`
	BriefUpdated time.Time        `json:"brief_updated,omitzero"`
}

type TerminationRef struct {
	SessionID   string `json:"session_id"`
	RunGen      uint64 `json:"run_gen"`
	MessagesURL string `json:"messages_url"`
}