feedback

Documentation

Index

• func CleanupSessions(root string, retention time.Duration) error
• func FeedbackRoot() string
• func SessionDir(id string) string
• func WriteRequest(dir string, q FeedbackRequest) error
• func WriteResult(dir string, r FeedbackResult) error
• type Artifact
• type FeedbackRequest
  • func ReadRequest(dir string) (FeedbackRequest, error)
• type FeedbackResult
  • func ReadResult(dir string) (FeedbackResult, error)
• type GraphEdge
• type GraphNode
• type GraphSource
• type Outcome
• type Server
  • func NewServer(id, dir string) (*Server, error)
  • func (s *Server) Addr() string
  • func (s *Server) SetGraphHTML(html []byte)
  • func (s *Server) SetGraphSource(src GraphSource)
  • func (s *Server) Start() error
  • func (s *Server) Wait() Outcome

Functions

func CleanupSessions

func CleanupSessions(root string, retention time.Duration) error

CleanupSessions removes feedback session directories under root whose most recent file was modified longer ago than retention. It is best-effort: a missing root is not an error, and a failure to remove one directory does not stop the sweep or fail the caller. The session directory is ephemeral scratch — the durable artifact is whatever the agent chose to persist from the result — so aged sessions are safe to reclaim.

func FeedbackRoot

func FeedbackRoot() string

FeedbackRoot returns the directory holding all feedback session directories: <configdir>/feedback/.

func SessionDir

func SessionDir(id string) string

SessionDir returns the directory holding a feedback session's files: <configdir>/feedback/<id>/.

func WriteRequest

func WriteRequest(dir string, q FeedbackRequest) error

WriteRequest persists q to <dir>/request.json.

func WriteResult

func WriteResult(dir string, r FeedbackResult) error

WriteResult persists r to <dir>/result.json.

Types

type Artifact

type Artifact struct {
	Format string `json:"format"`
	Path   string `json:"path"`
}

Artifact is one output produced by a feedback surface, referenced by path. The format names how to interpret the file; the surface writes it natively.

type FeedbackRequest

type FeedbackRequest struct {
	ID           string   `json:"id"`
	Surface      string   `json:"surface"`
	Mode         string   `json:"mode"`
	Instructions string   `json:"instructions"`
	Context      []string `json:"context"`
	Workspace    string   `json:"workspace,omitempty"`
	// Mermaid is an optional diagram source used to seed the canvas surface:
	// the frontend converts it to editable Excalidraw elements as initialData
	// when no prior draft exists.
	Mermaid string `json:"mermaid,omitempty"`
	Output  string `json:"output"`
	// Focus is the ego note id for the graph surface: the neighborhood the human
	// is asked to react to. AllowedNodes is the resolved scope — the exact set of
	// note ids the surface may show. The agent supplies the scope; the server
	// never widens it, so what the human sees is bounded by what the agent chose.
	Focus        string   `json:"focus,omitempty"`
	AllowedNodes []string `json:"allowed_nodes,omitempty"`
}

FeedbackRequest is prepared before a session launches. It describes what the human is being asked to do; the surface renders it and never infers intent. An absent Workspace means bootstrap/create.

func ReadRequest

func ReadRequest(dir string) (FeedbackRequest, error)

ReadRequest reads <dir>/request.json.

type FeedbackResult

type FeedbackResult struct {
	ID        string     `json:"id"`
	Surface   string     `json:"surface"`
	Status    string     `json:"status"`
	Artifacts []Artifact `json:"artifacts"`
}

FeedbackResult is the thin envelope returned after submission. Surface-specific shape lives inside the referenced artifact files, not in this struct.

func ReadResult

func ReadResult(dir string) (FeedbackResult, error)

ReadResult reads <dir>/result.json.

type GraphEdge

type GraphEdge struct {
	Source     string `json:"source"`
	Target     string `json:"target"`
	Type       string `json:"type,omitempty"`
	Annotation string `json:"annotation,omitempty"`
}

type GraphNode

type GraphNode struct {
	ID     string   `json:"id"`
	Title  string   `json:"title"`
	Type   string   `json:"type"`
	Status string   `json:"status"`
	Tags   []string `json:"tags"`
	Body   string   `json:"body"`
	Zone   string   `json:"zone,omitempty"`
	Degree int      `json:"degree"`
}

GraphNode and GraphEdge are the surface-native shape the graph feedback surface renders. They mirror the interactive viewer's /graph payload so the same frontend (graph.html) can drive against either server.

type GraphSource

type GraphSource interface {
	Graph() ([]GraphNode, []GraphEdge, error)
}

GraphSource supplies the candidate notebook graph for the graph surface. The server, not the source, applies the request's AllowedNodes bound — the source is deliberately scope-agnostic so the bound has a single enforcement point.

type Outcome

type Outcome string

Outcome is the terminal result of a feedback session's blocking Wait.

const (
	OutcomeSubmitted Outcome = "submitted"
	OutcomeCancelled Outcome = "cancelled"
)

type Server

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

Server hosts a single feedback session over an ephemeral loopback listener. The process is disposable; the session directory on disk is durable.

func NewServer

func NewServer(id, dir string) (*Server, error)

NewServer creates a server for session id whose files live in dir.

func (*Server) Addr

func (s *Server) Addr() string

Addr is the concrete host:port the server is listening on.

func (*Server) SetGraphHTML

func (s *Server) SetGraphHTML(html []byte)

SetGraphHTML attaches the graph-viewer HTML shell served at / for the graph surface, in place of the embedded canvas bundle.

func (*Server) SetGraphSource

func (s *Server) SetGraphSource(src GraphSource)

SetGraphSource attaches the graph data provider used by the /graph endpoint.

func (*Server) Start

func (s *Server) Start() error

Start binds an ephemeral loopback port and begins serving. It does not block.

func (*Server) Wait

func (s *Server) Wait() Outcome

Wait blocks until the session is submitted or cancelled, then returns the outcome. It shuts the server down gracefully so the in-flight submit/cancel request that produced the outcome finishes flushing its response to the client before the connection closes — an abrupt Close races that response and surfaces as an EOF on the client.