gateway

type FileAttachment struct {
	Filename string
	MimeType string
	Content  []byte
}

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

type Gateway interface {
	// Configure runs once at gateway startup. Settings come from the
	// HCL `settings = { ... }` map. The api handle is squadron's
	// SquadronAPI implementation reachable over the broker stream.
	//
	// Implementations should perform their startup catch-up here
	// (ListHumanInputs with a `Since` derived from local checkpoint).
	Configure(ctx context.Context, settings map[string]string, api SquadronAPI) error

	// OnHumanInputRequested is invoked once per new request that
	// squadron observes. Gateways post the question to their external
	// system and arrange for the user's reply to flow back via
	// SquadronAPI.ResolveHumanInput.
	OnHumanInputRequested(ctx context.Context, rec HumanInputRecord) error

	// OnHumanInputResolved is invoked once per resolution event,
	// regardless of who originated the resolution (this gateway, a
	// commander operator, another gateway, the agent timing out).
	// Gateways update their external surface to reflect the answer.
	OnHumanInputResolved(ctx context.Context, rec HumanInputRecord) error

	// OnNotification is invoked when a mission reaches a terminal state
	// (completed, failed, stopped) and the mission opted into gateway
	// notifications. Gateways post an informational message to their
	// external system; there is nothing for the user to act on.
	OnNotification(ctx context.Context, rec NotificationRecord) error

	// PostMessage posts a message to the gateway's external system. The
	// payload is the raw, gateway-schema-shaped JSON the agent produced for
	// the builtins.gateway.post tool; the gateway parses it itself.
	PostMessage(ctx context.Context, req PostMessageRequest) error

	// MessageToolSpec returns the description + optional JSON Schema squadron
	// uses to present the builtins.gateway.post tool to the LLM. Return a zero
	// MessageToolSpec to accept squadron's default { message } shape.
	MessageToolSpec(ctx context.Context) (MessageToolSpec, error)

	// Shutdown is invoked once when squadron is tearing the subprocess
	// down. Release external resources here (close the Discord
	// session, flush queues, persist checkpoint).
	Shutdown(ctx context.Context) error
}

type HostPlugin struct {
	plugin.Plugin
	// API is squadron's implementation of the SquadronAPI surface. The
	// host plugin registers it on a broker stream and hands the stream
	// id to the gateway during Configure so the gateway can dial back.
	API SquadronAPI
}

type HumanInputFilter struct {
	// State narrows by lifecycle state. Empty means both open + resolved.
	State HumanInputState
	// MissionID restricts to a specific mission run.
	MissionID string
	// Since is the catch-up cursor: rows whose requested_at OR
	// resolved_at is at or after this time. Use for reconnect / startup
	// backfill — pass the latest event timestamp the gateway has
	// already processed locally.
	Since time.Time
	// OldestFirst flips the default newest-first ordering. Use this
	// when replaying for catch-up so events are processed in the order
	// they happened.
	OldestFirst bool
	// Limit caps the page size. 0 means "use server default".
	Limit int
	// Offset skips that many results from the start of the page.
	Offset int
}

type HumanInputRecord struct {
	ID                string
	MissionID         string
	MissionName       string
	TaskID            string
	TaskName          string
	ToolCallID        string
	Question          string
	ShortSummary      string
	AdditionalContext string
	Choices           []string
	// MultiSelect is true when the human may pick 1+ choices rather
	// than exactly one. When true, the resolved Response is a JSON-
	// encoded string array (e.g. `["A","C"]`); when false, Response is
	// the single chosen string. Always false for free-text questions.
	MultiSelect     bool
	State           HumanInputState
	RequestedAt     time.Time
	ResolvedAt      time.Time // zero when State is open
	Response        string
	ResponderUserID string
}

type HumanInputState string

type MessageToolSpec struct {
	// Description is appended to the tool description so the LLM knows how to
	// format messages for this gateway.
	Description string
	// ParamsSchema is an optional JSON Schema (object) for the tool's
	// parameters. Empty → squadron's default { message } shape.
	ParamsSchema string
}

type NotificationRecord struct {
	MissionID   string
	MissionName string
	// Event is one of "mission_completed" or "mission_failed".
	Event      string
	Title      string
	Message    string
	OccurredAt time.Time
	// Error is set when Event is "mission_failed", empty otherwise.
	Error string
	// Channel is an optional per-mission destination override. When
	// empty the gateway posts to its globally configured default channel.
	Channel string
}

type PostMessageRequest struct {
	Payload     string
	Attachments []FileAttachment
}

type ResolveResult struct {
	// Record is the canonical row after the call. For not-found this
	// is the zero value.
	Record HumanInputRecord
	// AlreadyResolved is true when the request was resolved by some
	// other actor before this call landed. Display "already answered
	// by X" rather than confirming the gateway's user's submission.
	AlreadyResolved bool
	// NotFound is true when the tool_call_id is unknown to squadron.
	// Most commonly: the row was trimmed from the store, or a stale
	// event made it into the gateway's queue. Treat as a no-op.
	NotFound bool
}

type SquadronAPI interface {
	ListHumanInputs(ctx context.Context, filter HumanInputFilter) ([]HumanInputRecord, int, error)
	ResolveHumanInput(ctx context.Context, toolCallID, response, responderUserID string) (ResolveResult, error)
}