channels

type ApprovalDecision struct {
	TaskID   string // must match the ApprovalRequest.TaskID
	Decision string // "approve" | "reject"
	Approver string // who acted (platform user id / name), for audit
	// ApproverEmail is the approver's resolved email (#313). Adapters populate
	// it (e.g. Slack via users.info) so the runtime's approver allowlist check
	// is adapter-agnostic. Empty when the adapter couldn't resolve it — the
	// runtime fails closed against a configured allowlist.
	ApproverEmail string
	Note          string // optional justification
}

type ApprovalDeliverer interface {
	// DeliverApproval posts the interactive approval request to req.Target.
	DeliverApproval(ctx context.Context, req ApprovalRequest) error
	// SetApprovalResolver wires the callback the adapter invokes when an
	// approver acts. The runtime sets this once at startup.
	SetApprovalResolver(r ApprovalResolver)
}

type ApprovalRequest struct {
	TaskID  string        // the deferred A2A task; the resolution key
	Tool    string        // the tool call awaiting approval
	Context string        // rendered context_template (what the agent wants to do)
	Timeout time.Duration // how long until auto-deny
	Target  string        // adapter-specific destination (e.g. a Slack channel "#oncall")
}

type ApprovalResolver func(ctx context.Context, d ApprovalDecision) error

type Attachment struct {
	Name     string `json:"name,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
	URL      string `json:"url,omitempty"`
}

type ChannelConfig struct {
	Adapter     string            `yaml:"adapter"`
	WebhookPort int               `yaml:"webhook_port,omitempty"`
	WebhookPath string            `yaml:"webhook_path,omitempty"`
	Settings    map[string]string `yaml:"settings,omitempty"`
}

type ChannelEvent struct {
	Channel     string `json:"channel"`
	WorkspaceID string `json:"workspace_id"`
	UserID      string `json:"user_id"`
	// UserEmail is the sender's resolved email (e.g. Slack users.info,
	// cached), when the adapter can determine it. It rides to the A2A server
	// as the task's on-behalf-of identity so delegated (auth.type=user) MCP
	// tools key consent + per-user tokens on the HUMAN who sent the message,
	// not the runtime's loopback identity (field-hit 2026-07-21: a consent DM
	// addressed to "forge-internal"). Best-effort — empty when unresolvable.
	UserEmail   string          `json:"user_email,omitempty"`
	ThreadID    string          `json:"thread_id,omitempty"`
	MessageID   string          `json:"message_id,omitempty"` // per-message ID for reply targeting
	Message     string          `json:"message"`
	Attachments []Attachment    `json:"attachments,omitempty"`
	Raw         json.RawMessage `json:"raw,omitempty"`
}

type ChannelOrigin struct {
	Adapter  string // e.g. "slack"
	Channel  string // native channel / DM id
	ThreadTS string // thread to reply in (optional)
	UserID   string // native user id (skips an email lookup)
}

type ChannelPlugin interface {
	// Name returns the adapter name (e.g. "slack", "telegram").
	Name() string
	// Init configures the plugin from a ChannelConfig.
	Init(cfg ChannelConfig) error
	// Start begins listening for events and dispatching them to handler.
	// It blocks until ctx is cancelled.
	Start(ctx context.Context, handler EventHandler) error
	// Stop gracefully shuts down the plugin.
	Stop() error
	// NormalizeEvent converts raw platform bytes into a ChannelEvent.
	NormalizeEvent(raw []byte) (*ChannelEvent, error)
	// SendResponse delivers an A2A response back to the originating platform.
	SendResponse(event *ChannelEvent, response *a2a.Message) error
}

type ConsentCanceler func(ctx context.Context, subject, server string) error

type ConsentDeliverer interface {
	// DeliverConsent presents the consent prompt to req.Subject (or req.Origin).
	DeliverConsent(ctx context.Context, req ConsentPrompt) error
	// SetConsentCanceler wires the callback the adapter invokes when the user
	// cancels. The runtime sets this once at startup; may be a no-op.
	SetConsentCanceler(c ConsentCanceler)
}

type ConsentPrompt struct {
	Subject      string         // the requesting user (email preferred) — who to reach
	Server       string         // MCP server name — for the prompt copy
	AuthorizeURL string         // the login link the user opens (a URL button)
	Deadline     time.Time      // the gate timeout — rendered as "expires …"
	Origin       *ChannelOrigin // optional: reply in the origin thread if the request came via this channel
}

type EventHandler func(ctx context.Context, event *ChannelEvent) (*a2a.Message, error)

type Logger interface {
	Info(msg string, fields map[string]any)
	Warn(msg string, fields map[string]any)
	Error(msg string, fields map[string]any)
	Debug(msg string, fields map[string]any)
}

type LoggerAware interface {
	SetLogger(Logger)
}

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