surfaces

Documentation

Index

• type ChatMessage
• type ChatRequest
• type ChatResponse
• type CreateRequest
• type DBTX
• type Handler
  • func NewHandler(store Storer, agent agentapi.Chatter, logger *zap.SugaredLogger) *Handler
  • func (h *Handler) Chat(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) GetOne(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) List(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) ListMessages(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) Respond(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) Update(w http.ResponseWriter, r *http.Request)
• type ListFilter
• type RespondRequest
• type Store
  • func NewStore(pool DBTX, eideticClient eidetic.Client, logger *zap.SugaredLogger) *Store
  • func (s *Store) ActiveCount(ctx context.Context) (int, error)
  • func (s *Store) AddMessage(ctx context.Context, surfaceID uuid.UUID, role, content string) (*ChatMessage, error)
  • func (s *Store) Create(ctx context.Context, req CreateRequest) (*Surface, error)
  • func (s *Store) DueReminders(ctx context.Context) ([]Surface, error)
  • func (s *Store) Get(ctx context.Context, id uuid.UUID) (*Surface, error)
  • func (s *Store) List(ctx context.Context, f ListFilter) ([]Surface, error)
  • func (s *Store) ListMessages(ctx context.Context, surfaceID uuid.UUID) ([]ChatMessage, error)
  • func (s *Store) Migrate(ctx context.Context) error
  • func (s *Store) Respond(ctx context.Context, id uuid.UUID, req RespondRequest) (*Surface, error)
  • func (s *Store) Update(ctx context.Context, id uuid.UUID, req UpdateRequest) (*Surface, error)
  • func (s *Store) WriteConversationToEidetic(ctx context.Context, surf *Surface, messages []ChatMessage) error
• type Storer
• type Surface
• type SurfaceStatus
• type SurfaceType
• type UpdateRequest

Types

type ChatMessage

type ChatMessage struct {
	ID        uuid.UUID `json:"id"`
	SurfaceID uuid.UUID `json:"surface_id"`
	Role      string    `json:"role"` // "user" or "assistant"
	Content   string    `json:"content"`
	CreatedAt time.Time `json:"created_at"`
}

ChatMessage is one message in a surface conversation thread.

type ChatRequest

type ChatRequest struct {
	Message string `json:"message"`
}

ChatRequest is the payload for POST /api/surfaces/:id/chat.

type ChatResponse

type ChatResponse struct {
	UserMessage      ChatMessage `json:"user_message"`
	AssistantMessage ChatMessage `json:"assistant_message"`
}

ChatResponse is the response from the chat endpoint.

type CreateRequest

type CreateRequest struct {
	Content         string      `json:"content"`
	SurfaceType     SurfaceType `json:"surface_type"`
	Priority        int         `json:"priority"`
	RelatedEntryIDs []uuid.UUID `json:"related_entry_ids"`
	Tags            []string    `json:"tags"`
	ReasoningCycle  uuid.UUID   `json:"reasoning_cycle"`
	TriggerAt       *time.Time  `json:"trigger_at,omitempty"`
}

CreateRequest holds the fields needed to insert a new surface.

type DBTX

type DBTX interface {
	Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}

DBTX is the minimal database interface used by Store. Both *pgxpool.Pool and pgxmock satisfy this.

type Handler

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

Handler wires HTTP routes to the surfaces store.

func NewHandler

func NewHandler(store Storer, agent agentapi.Chatter, logger *zap.SugaredLogger) *Handler

NewHandler creates a handler.

func (*Handler) Chat

func (h *Handler) Chat(w http.ResponseWriter, r *http.Request)

Chat handles a conversation turn on a surface — stores user message, calls the agent, stores response.

func (*Handler) GetOne

func (h *Handler) GetOne(w http.ResponseWriter, r *http.Request)

GetOne returns a single surface by ID.

func (*Handler) List

func (h *Handler) List(w http.ResponseWriter, r *http.Request)

List returns surfaces matching query filters.

func (*Handler) ListMessages

func (h *Handler) ListMessages(w http.ResponseWriter, r *http.Request)

ListMessages returns the conversation thread for a surface.

func (*Handler) Respond

func (h *Handler) Respond(w http.ResponseWriter, r *http.Request)

Respond records the user's answer to a question surface.

func (*Handler) Update

func (h *Handler) Update(w http.ResponseWriter, r *http.Request)

Update applies a status change (dismiss, mark acted, etc).

type ListFilter

type ListFilter struct {
	Status      string
	SurfaceType string
	Limit       int
}

ListFilter holds query-string filters for GET /api/surfaces.

type RespondRequest

type RespondRequest struct {
	Response string `json:"response"`
}

RespondRequest is the payload for POST /api/surfaces/:id/respond.

type Store

type Store struct {
	OnEideticWrite func() // called after successful Eidetic write-back; optional
	// contains filtered or unexported fields
}

Store handles all database operations for surfaces.

func NewStore

func NewStore(pool DBTX, eideticClient eidetic.Client, logger *zap.SugaredLogger) *Store

NewStore creates a new Store backed by pool.

func (*Store) ActiveCount

func (s *Store) ActiveCount(ctx context.Context) (int, error)

ActiveCount returns the number of active surfaces.

func (*Store) AddMessage

func (s *Store) AddMessage(ctx context.Context, surfaceID uuid.UUID, role, content string) (*ChatMessage, error)

AddMessage inserts a chat message for a surface.

func (*Store) Create

func (s *Store) Create(ctx context.Context, req CreateRequest) (*Surface, error)

Create inserts a new surface and returns it.

func (*Store) DueReminders

func (s *Store) DueReminders(ctx context.Context) ([]Surface, error)

DueReminders returns active surfaces whose trigger_at has passed.

func (*Store) Get

func (s *Store) Get(ctx context.Context, id uuid.UUID) (*Surface, error)

Get returns a single surface by ID.

func (*Store) List

func (s *Store) List(ctx context.Context, f ListFilter) ([]Surface, error)

List returns surfaces matching the given filter, ordered by priority then recency.

func (*Store) ListMessages

func (s *Store) ListMessages(ctx context.Context, surfaceID uuid.UUID) ([]ChatMessage, error)

ListMessages returns all chat messages for a surface in chronological order.

func (*Store) Migrate

func (s *Store) Migrate(ctx context.Context) error

Migrate creates the agenticme_surfaces table if it doesn't exist.

func (*Store) Respond

func (s *Store) Respond(ctx context.Context, id uuid.UUID, req RespondRequest) (*Surface, error)

Respond records the user's answer to a question surface and writes a Q+A entry back to Eidetic.

func (*Store) Update

func (s *Store) Update(ctx context.Context, id uuid.UUID, req UpdateRequest) (*Surface, error)

Update applies a partial update to a surface (e.g. dismiss).

func (*Store) WriteConversationToEidetic

func (s *Store) WriteConversationToEidetic(ctx context.Context, surf *Surface, messages []ChatMessage) error

WriteConversationToEidetic writes the full surface conversation to Eidetic.

type Storer

type Storer interface {
	List(ctx context.Context, f ListFilter) ([]Surface, error)
	Get(ctx context.Context, id uuid.UUID) (*Surface, error)
	Update(ctx context.Context, id uuid.UUID, req UpdateRequest) (*Surface, error)
	Respond(ctx context.Context, id uuid.UUID, req RespondRequest) (*Surface, error)
	AddMessage(ctx context.Context, surfaceID uuid.UUID, role, content string) (*ChatMessage, error)
	ListMessages(ctx context.Context, surfaceID uuid.UUID) ([]ChatMessage, error)
	WriteConversationToEidetic(ctx context.Context, surf *Surface, messages []ChatMessage) error
}

Storer is the interface the handler needs from the persistence layer.

type Surface

type Surface struct {
	ID              uuid.UUID     `json:"id"`
	Content         string        `json:"content"`
	SurfaceType     SurfaceType   `json:"surface_type"`
	Priority        int           `json:"priority"`
	Status          SurfaceStatus `json:"status"`
	RelatedEntryIDs []uuid.UUID   `json:"related_entry_ids"`
	Tags            []string      `json:"tags"`
	UserResponse    *string       `json:"user_response,omitempty"`
	RespondedAt     *time.Time    `json:"responded_at,omitempty"`
	ReasoningCycle  *uuid.UUID    `json:"reasoning_cycle,omitempty"`
	TriggerAt       *time.Time    `json:"trigger_at,omitempty"`
	CreatedAt       time.Time     `json:"created_at"`
	UpdatedAt       time.Time     `json:"updated_at"`
	ExpiredAt       *time.Time    `json:"expired_at,omitempty"`
}

Surface is an agent-produced item surfaced to the user.

type SurfaceStatus

type SurfaceStatus string

SurfaceStatus tracks the lifecycle of a surface.

const (
	StatusActive    SurfaceStatus = "active"
	StatusDismissed SurfaceStatus = "dismissed"
	StatusAnswered  SurfaceStatus = "answered"
	StatusExpired   SurfaceStatus = "expired"
	StatusActed     SurfaceStatus = "acted"
)

type SurfaceType

type SurfaceType string

SurfaceType identifies what kind of surface the agent produced.

const (
	TypeInsight    SurfaceType = "insight"
	TypeQuestion   SurfaceType = "question"
	TypeWarning    SurfaceType = "warning"
	TypeReminder   SurfaceType = "reminder"
	TypeConnection SurfaceType = "connection"
)

type UpdateRequest

type UpdateRequest struct {
	Status *SurfaceStatus `json:"status,omitempty"`
}

UpdateRequest is the payload for PATCH /api/surfaces/:id.