inbox

Documentation

Overview

Package inbox provides a file-based message inbox for piglet. External processes drop JSON envelopes into a directory; the scanner picks them up and injects them into the agent loop.

Index

• Constants
• func Register(e *sdk.Extension)
• func Validate(env *Envelope) (bool, string)
• type Ack
• type Deliverer
• type Envelope
• type Heartbeat
• type Scanner
  • func New(inboxDir, cwd string, pid int, d Deliverer) *Scanner
  • func (s *Scanner) Start(ctx context.Context)
  • func (s *Scanner) Stats() Stats
  • func (s *Scanner) Stop()
• type Stats

Constants

const (
	DefaultScanInterval = 750 * time.Millisecond
	HeartbeatInterval   = 2 * time.Second
	MaxFileBytes        = 32 * 1024
	MaxTextRunes        = 8000
	DedupCap            = 1000
	AckMaxAge           = time.Hour
	PruneInterval       = time.Minute

	ModeQueue     = "queue"
	ModeInterrupt = "interrupt"
)

Functions

func Register

func Register(e *sdk.Extension)

Register registers the inbox extension's event handler and inbox_status tool. No OnInit needed — inbox starts on EventAgentStart.

func Validate

func Validate(env *Envelope) (bool, string)

Validate checks an envelope for structural validity.

Types

type Ack

type Ack struct {
	ID     string `json:"id"`
	Status string `json:"status"`
	Reason string `json:"reason,omitzero"`
	Ts     string `json:"ts"`
}

Ack is written after processing an envelope.

type Deliverer

type Deliverer interface {
	SendMessage(content string)
	Steer(content string)
	Notify(msg string)
}

Deliverer injects messages into the agent loop. *sdk.Extension satisfies this interface.

type Envelope

type Envelope struct {
	Version int    `json:"version"`
	ID      string `json:"id"`
	Text    string `json:"text"`
	Mode    string `json:"mode,omitzero"`
	Created string `json:"created,omitzero"`
	TTL     int    `json:"ttl,omitzero"`
	Source  string `json:"source,omitzero"`
}

Envelope is an inbound message from an external process.

type Heartbeat

type Heartbeat struct {
	PID       int    `json:"pid"`
	CWD       string `json:"cwd"`
	Started   string `json:"started"`
	Heartbeat string `json:"heartbeat"`
}

Heartbeat is written periodically to the registry.

type Scanner

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

Scanner watches the inbox directory and delivers messages.

func New

func New(inboxDir, cwd string, pid int, d Deliverer) *Scanner

New creates a scanner. Call Start to begin scanning.

func (*Scanner) Start

func (s *Scanner) Start(ctx context.Context)

Start launches the scan and heartbeat goroutines.

func (*Scanner) Stats

func (s *Scanner) Stats() Stats

Stats returns a copy of the current delivery statistics.

func (*Scanner) Stop

func (s *Scanner) Stop()

Stop cancels the scanner and waits for goroutines to finish.

type Stats

type Stats struct {
	Delivered  int       `json:"delivered"`
	Failed     int       `json:"failed"`
	Duplicates int       `json:"duplicates"`
	Expired    int       `json:"expired"`
	StartedAt  time.Time `json:"startedAt"`
}

Stats tracks delivery counts for the current session.