delivery

type Adapter interface {
	// Harness is the harness's name, such as "codex".
	Harness() string
	// Validate checks that the exact session can receive deliveries. It returns
	// ErrTargetAbsent for a session that doesn't exist and ErrSubAgent for a sub-agent.
	Validate(ctx context.Context, sessionID string) error
	// WaitsForIdle is true when bundles go only to a hook waiting while the session is
	// idle, and false when the harness queues bundles itself.
	WaitsForIdle() bool
	// Hand gives a bundle to the session. confirmed is true when the harness's
	// acceptance alone confirms the session received it. ErrBusy means the session
	// can't take it now and the bundle stays pending.
	Hand(ctx context.Context, h Handover) (confirmed bool, err error)
}

type AgentKey struct {
	Server   string
	MemberID string
	Board    string
	Name     string
}

type AgentProblem struct {
	Agent  AgentRef `json:"agent"`
	Reason string   `json:"reason"`
}

type AgentRef struct {
	Server   string `json:"server"`
	Board    string `json:"board"`
	Name     string `json:"name"`
	MemberID string `json:"member_id,omitempty"`
}

type Binding struct {
	RetainSiblings bool `json:"-"`
	Generation     uint64
	Agent          AgentRef
	Session        SessionKey
	BoundAt        time.Time
}

type BindingStatus struct {
	Agent   AgentRef `json:"agent"`
	Session string   `json:"session"`
	// Open is true while the session is open.
	Open bool `json:"open,omitempty"`
	// Turned is true once the session has run a turn, so the harness can resume it.
	Turned bool `json:"turned,omitempty"`
}

type BoardCreateOptions struct {
	Name       string `json:"name,omitempty"`
	Title      string `json:"title,omitempty"`
	Template   string `json:"template,omitempty"`
	Charter    string `json:"charter,omitempty"`
	Preset     string `json:"preset,omitempty"`
	Visibility string `json:"visibility,omitempty"`
}

type Build struct {
	// Version is the release version, compared as a semantic version.
	Version string `json:"version"`
	// Commit and CommitTime name the Git commit the binary was built from, when known.
	Commit     string    `json:"commit,omitempty"`
	CommitTime time.Time `json:"commit_time,omitzero"`
}

type Class string

type Config struct {
	Journal Journal
	// ResolveAgent verifies a seat using its saved credential. Nil is used by
	// adapters whose agent references are already trusted, such as contract fixtures.
	ResolveAgent func(context.Context, AgentRef) (AgentRef, error)
	Adapters     []Adapter
	// Connect returns the connection to one server. It is called once per server URL,
	// when the first agent on that server is bound.
	Connect func(serverURL string) Server
	Control Control
	// Processes checks that each open session's harness still runs. Nil means sessions
	// close only when their end hook says so.
	Processes Processes
	Clock     clock.Clock
	Log       *slog.Logger
	// PID and Build are reported by the status operation.
	PID   int
	Build Build
	// IdleExit overrides how long the daemon runs with no open session; zero means
	// the default.
	IdleExit time.Duration
	// Tickets holds the launch tickets aboard swarm up writes. Nil means a launch
	// ticket binds nothing.
	Tickets Tickets
	// Seats lists and joins boards for sessions through the machine's delegation
	// (seats.go). Nil means the boards and join operations refuse.
	Seats Seats
	// contains filtered or unexported fields
}

type Control interface {
	Accept() (net.Conn, error)
	Close() error
}

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

type Delivery struct {
	HandoffID string
	ID        int64
	Agent     AgentRef
	// Session and Boot are the session the delivery was last handed to.
	Session  SessionKey
	Boot     string
	State    State
	Seqs     []int
	Attempts int
	// Reason is the code of the last failure, such as codex_target_absent.
	Reason    string
	RetryAt   time.Time
	CreatedAt time.Time
	UpdatedAt time.Time
	// AcceptedAt is when the harness accepted the delivery: a waiting hook took it, its
	// queue took it, or its extension added it. TurnStartedAt is when the session's next
	// turn started after that. Both are zero until then.
	AcceptedAt    time.Time
	TurnStartedAt time.Time
	// Stalled is set when the delivery was handed to an idle session that started no
	// turn within StallAfter. It is reported, never handed again because of it.
	Stalled bool
}

type HandoffManifest struct {
	ID          string
	Session     SessionKey
	Boot        string
	Class       Class
	PayloadHash string
	Parts       []HandoffPart
	CreatedAt   time.Time
}

type HandoffPart struct {
	Agent      AgentRef
	Generation uint64
	Seqs       []int
	DeliveryID int64
}

type HandoffWaiter interface {
	DeliverHandoff(context.Context, Handover) error
}

type Handover struct {
	SessionID string
	HandoffID string
	Class     Class
	// ID is the first delivery the bundle carries, which a harness extension names when
	// it confirms the bundle.
	ID     int64
	Bundle string
	// Waiter is the hook or extension connection waiting for this session to be given a
	// bundle, or nil.
	Waiter Waiter
}

type Head struct {
	Board string
	Seq   int
	Read  *ReadPosition
}

type HeldMode struct {
	Mode     Mode
	Revision int64
}

type Journal interface {
	SaveSession(ctx context.Context, s SessionRecord) error
	Sessions(ctx context.Context) ([]SessionRecord, error)
	Bind(ctx context.Context, b Binding) error
	BindGeneration(ctx context.Context, b Binding, advance bool) (Binding, error)
	PrepareHandoff(ctx context.Context, manifest HandoffManifest) (HandoffManifest, error)
	ConfirmHandoff(ctx context.Context, id string, session SessionKey, boot string, surviving []AgentKey, at time.Time) ([]Delivery, error)
	Handoffs(ctx context.Context) ([]HandoffManifest, error)
	Bindings(ctx context.Context) ([]Binding, error)
	// ResolveIdentity attaches legacy state to the seat proved by its own token.
	// It never changes rows that already name a different seat.
	ResolveIdentity(ctx context.Context, old, resolved AgentRef) error
	// SetMode records an agent's delivery mode: one set on this machine, or the last one
	// read from a server that holds it.
	SetMode(ctx context.Context, agent AgentRef, mode Mode) error
	// Modes returns every agent's recorded delivery mode.
	Modes(ctx context.Context) (map[AgentRef]Mode, error)
	// AddDelivery records a new delivery with its messages and returns its id.
	AddDelivery(ctx context.Context, d Delivery) (int64, error)
	// UpdateDelivery saves a delivery's state, session, attempts, reason and retry
	// time. Its messages don't change.
	UpdateDelivery(ctx context.Context, d Delivery) error
	// Deliveries returns the deliveries in any of the given states, oldest first.
	Deliveries(ctx context.Context, states ...State) ([]Delivery, error)
}

type Message = deliverytext.Message

type Mode string

type Presence string

type Process struct {
	PID   int   `json:"pid"`
	Start int64 `json:"start"`
}

type Processes interface {
	Alive(p Process) bool
	// StartTime returns when a running process started, in the system's own units, for
	// a client that names only its process id. ok is false when it can't be read.
	StartTime(pid int) (start int64, ok bool)
}

type ReadPosition struct {
	Agent    string
	MemberID string
	UpTo     int
}

type Request struct {
	V       int    `json:"v"`
	Op      string `json:"op"`
	Harness string `json:"harness,omitempty"`
	Session string `json:"session,omitempty"`
	// Boot is the session's boot id. Empty means the boot the daemon has on record.
	Boot string `json:"boot,omitempty"`
	// Source is what started the session: startup, resume, clear or compact.
	Source string `json:"source,omitempty"`
	// Resumed marks a wait that reconnects after the daemon went away, so it doesn't
	// count as the session's next event.
	Resumed bool `json:"resumed,omitempty"`
	// Wake marks a prompt that is the bundle a stop hook just woke the session with, not
	// a later event; it doesn't confirm that bundle.
	Wake bool `json:"wake,omitempty"`
	// Started is when the hook process started. A wait from a stop hook that started
	// before the session's latest prompt belongs to an earlier turn, and is released.
	Started time.Time `json:"started,omitzero"`
	Agent   *AgentRef `json:"agent,omitempty"`
	// Mode is the delivery mode an OpMode request sets; empty only shows it.
	Mode Mode `json:"mode,omitempty"`
	// Revision, on an OpMode request that sets a mode, says the mode is the one the
	// agent's server holds, at this revision: the daemon takes it as if it had read it
	// from the server. Without it the mode is kept on this machine only.
	Revision int64 `json:"revision,omitempty"`
	// Process is the harness process the request came from, when the caller found it.
	Process *Process `json:"process,omitempty"`
	// ReplyTo is the sequence number whose replies an OpHold keeps out of bundles.
	ReplyTo int `json:"reply_to,omitempty"`
	// Seqs are the messages an OpClaim records as received.
	Seqs []int `json:"seqs,omitempty"`
	// ID is the delivery an extension's OpReceived confirms.
	ID           int64    `json:"id,omitempty"`
	HandoffID    string   `json:"handoff_id,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
	// Cwd, HarnessVersion and ExtensionVersion describe an extension's session in its
	// OpHello, for the daemon's log and aboard doctor.
	Cwd              string `json:"cwd,omitempty"`
	HarnessVersion   string `json:"harness_version,omitempty"`
	ExtensionVersion string `json:"extension_version,omitempty"`
	// Subagent is the harness's id for the subagent an OpHello comes from, or empty for
	// the session's own conversation.
	Subagent string `json:"subagent,omitempty"`
	// Launch is a launch ticket from ABOARD_LAUNCH, on a register or a hello: the daemon
	// binds the session to the agent the ticket names, once.
	Launch string `json:"launch,omitempty"`
	// Server is the server an OpBoards lists boards on; empty means the server of the
	// session's seats.
	Server string `json:"server,omitempty"`
	// Lifecycle filters an OpBoards list: active (the default when empty), archived or
	// all. It never widens what the delegation may list.
	Lifecycle string `json:"lifecycle,omitempty"`
	// Role is the role an OpJoin joins as; empty means member.
	Role           string              `json:"role,omitempty"`
	Create         *BoardCreateOptions `json:"create,omitempty"`
	AgentName      string              `json:"agent_name,omitempty"`
	IdempotencyKey string              `json:"idempotency_key,omitempty"`
}

type Response struct {
	V      int    `json:"v"`
	Event  string `json:"event,omitempty"`
	Bundle string `json:"bundle,omitempty"`
	// ID is the delivery an EventDeliver on an extension connection carries, which the
	// extension names when it confirms it.
	ID            int64    `json:"id,omitempty"`
	HandoffID     string   `json:"handoff_id,omitempty"`
	DeliveryClass Class    `json:"delivery_class,omitempty"`
	Capabilities  []string `json:"capabilities,omitempty"`
	// Notice names waiting messages without their content, in answer to OpBoundary.
	Notice string     `json:"notice,omitempty"`
	Boot   string     `json:"boot,omitempty"`
	Agents []AgentRef `json:"agents,omitempty"`
	Status *Status    `json:"status,omitempty"`
	// Mode is the agent's delivery mode, in answer to OpMode; Changed says whether the
	// request changed it. In answer to OpRegister and in EventWelcome, it is the mode of
	// the agent the session holds.
	Mode Mode `json:"mode,omitempty"`
	// Note, in answer to OpRegister and in EventWelcome, is what to add to the context
	// of a session that comes back: which agent it is again, with that agent's delivery
	// mode and its rule, or which agent it lost.
	Note    string `json:"note,omitempty"`
	Changed bool   `json:"changed,omitempty"`
	// Previous is the agent the session was bound to before an OpBind moved it to
	// another one; nil when the session had no agent or keeps the same one.
	Previous *AgentRef `json:"previous,omitempty"`
	// Reopened says an OpRegister opened a session that had closed: the harness resumed
	// it with the same session id. Agents then lists the agent it is bound to again.
	Reopened bool `json:"reopened,omitempty"`
	// Lost, in answer to OpRegister, is the agent the session filled until another
	// session resumed it; the session has no agent now.
	Lost *AgentRef `json:"lost,omitempty"`
	// Held says an OpHold took effect: the agent is bound to an open session here.
	Held bool `json:"held,omitempty"`
	// Claimed are the messages an OpClaim recorded; one already handed to a session isn't.
	Claimed []int `json:"claimed,omitempty"`
	// Received, in answer to OpInbox, are the agent's messages past its read position
	// that a session here has received; a command reading the inbox leaves them out.
	Received []int `json:"received,omitempty"`
	// Joined, in answer to OpJoin, is the seat the session has on the board now; Reused
	// says it is the session's earlier seat. Board and Member are the server's Board and
	// Member for it, as the API gives them.
	Joined *SeatRef        `json:"joined,omitempty"`
	Reused bool            `json:"reused,omitempty"`
	Board  json.RawMessage `json:"board,omitempty"`
	Member json.RawMessage `json:"member,omitempty"`
	// Server and Boards, in answer to OpBoards, are the boards the session's person can
	// see on that server, each the API's Board with seat, the session's seat on it.
	Server string            `json:"server,omitempty"`
	Boards []json.RawMessage `json:"boards,omitempty"`
	// ArchivedCount, in answer to OpBoards, is the server's count of archived boards in
	// the delegation's list scope; nil when the server sent none, which is not zero.
	ArchivedCount *int       `json:"archived_count,omitempty"`
	Error         *WireError `json:"error,omitempty"`
}

type SeatBoard struct {
	Name  string
	Board json.RawMessage
}

type SeatBoards struct {
	Boards        []SeatBoard
	ArchivedCount *int
}

type SeatCreateRequest struct {
	BoardCreateOptions
	Role, Name, Harness, Session, IdempotencyKey string
}

type SeatGrant struct {
	Seat   SeatRef
	Token  string
	Reused bool
	Board  json.RawMessage
	Member json.RawMessage
	Mode   Mode
}

type SeatRef struct {
	Server   string `json:"server"`
	Board    string `json:"board"`
	Name     string `json:"name"`
	MemberID string `json:"member_id,omitempty"`
}

type SeatRequest struct {
	Board, Role, Name, Harness, Session string
}

type Seats interface {
	// Boards lists the boards the person can see on server, filtered by lifecycle
	// (active, archived or all; empty means the server's default, active). ErrLoginMissing
	// means this machine has no key for it; ErrServerUnreachable and ErrServerOutdated
	// as for Join; a server's refusal is a *WireError, passed on as it is.
	Boards(ctx context.Context, server, lifecycle string) (SeatBoards, error)
	// Join asks server for the session's seat on a board. Errors are as for Boards; a
	// lost answer is ErrServerUnreachable, never a seat.
	Join(ctx context.Context, server string, req SeatRequest) (SeatGrant, error)
	Create(ctx context.Context, server string, req SeatCreateRequest) (SeatGrant, error)
	// Save writes a seat's token where the session's commands find it, whole or not at
	// all, replacing the seat's earlier token.
	Save(ctx context.Context, seat SeatRef, token string) error
	// SeatID returns the member id this machine keeps for an agent, if any.
	SeatID(agent AgentRef) (string, bool)
}

type Server interface {
	// Follow streams the heads of the human's boards and calls head for each, and for
	// each move of the read position of one of the human's agents (Head.Read), whoever
	// acknowledged, until ctx ends or the connection fails. connected is called once the
	// stream is open.
	Follow(ctx context.Context, connected func(), head func(Head)) error
	// Inbox returns the agent's unread messages, oldest first, its read position, and
	// its delivery mode as the server holds it, read together; mode is nil from a server
	// that doesn't hold delivery modes.
	Inbox(ctx context.Context, agent AgentRef) (msgs []Message, cursor int, mode *HeldMode, err error)
	// Ack moves the agent's read position up to seq.
	Ack(ctx context.Context, agent AgentRef, upTo int) error
	// SetPresence reports what the agent's session is doing, and the agent's delivery
	// mode, so senders can tell when a message will reach it.
	SetPresence(ctx context.Context, agent AgentRef, p Presence, mode Mode) error
}

type ServerStatus struct {
	URL       string `json:"url"`
	Connected bool   `json:"connected"`
	// Problem is login_missing, server_unreachable or empty.
	Problem string `json:"problem,omitempty"`
}

type SessionError struct {
	Err           error
	Message, Hint string
}

type SessionKey struct {
	Harness string `json:"harness"`
	ID      string `json:"id"`
}

type SessionRecord struct {
	Key  SessionKey
	Boot string
	Open bool
	// Process is the harness process the session runs in, or nil if it isn't known.
	Process *Process
	// Lost is the agent another session resumed while this one held it, or nil. The
	// session doesn't take it back when it starts again; it says so instead.
	Lost *AgentRef
	// Turned is true once the session has run a turn, which a harness needs before it
	// can resume the session (Claude Code saves a conversation only from its first turn).
	Turned    bool
	UpdatedAt time.Time
}

type State string

type Status struct {
	PID int `json:"pid"`
	// Build is the daemon's build; a daemon from before builds were reported leaves it
	// empty.
	Build        Build          `json:"build"`
	OpenSessions int            `json:"open_sessions"`
	Servers      []ServerStatus `json:"servers"`
	Attention    []StatusItem   `json:"attention"`
	Skipped      []StatusItem   `json:"skipped"`
	// Stalled are deliveries handed to an idle session that started no turn within
	// StallAfter, reason no_turn_started. They aren't handed again.
	Stalled []StatusItem `json:"stalled"`
	// MultiSeat says this daemon can bind several board seats to one session.
	MultiSeat bool            `json:"multi_seat,omitempty"`
	Agents    []AgentProblem  `json:"agents"`
	Bindings  []BindingStatus `json:"bindings"`
}

type StatusItem struct {
	ID     int64    `json:"id"`
	Agent  AgentRef `json:"agent"`
	Seqs   []int    `json:"seqs"`
	Reason string   `json:"reason"`
}

type TaskWorkServer interface {
	TaskWork(ctx context.Context, agent AgentRef) (*deliverytext.TaskWork, error)
}

type Tickets interface {
	// Take returns the agent a ticket names and removes the ticket, so it works once. ok
	// is false for a ticket that doesn't exist or was already taken.
	Take(ticket string) (agent AgentRef, ok bool, err error)
}

type Waiter interface {
	// Deliver sends the bundle, the delivery id first in it, and returns once the other
	// end has it. It returns ErrBusy if the connection went away first.
	Deliver(ctx context.Context, id int64, bundle string) error
	// Release tells a hook to exit without a bundle. An extension's connection stays
	// open, so it is told nothing.
	Release()
}

type WireError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Hint    string `json:"hint"`
	// Details is structured context passed on from a server's refusal, such as
	// agent_removed's agent, removed_at and removed_by.
	Details map[string]any `json:"details,omitempty"`
}