askuser

type Answer ¶

type Answer struct {
	Value  string            `json:"value,omitempty"`
	Text   string            `json:"text,omitempty"`
	Values map[string]string `json:"values,omitempty"`
}

Answer is what the user posts via /sessions/{id}/answer. One of Value / Text / Values is set; if Value and Text are both present, Value wins (it's the label of a clicked option, more authoritative than free-typed text on the same form). Values carries the field map of a structured form ask.

type AskRequest ¶

type AskRequest struct {
	ID            string   `json:"id"`
	SessionID     string   `json:"session_id"`
	AgentName     string   `json:"agent_name,omitempty"`
	Question      string   `json:"question"`
	Options       []Option `json:"options,omitempty"`
	AllowFreeform bool     `json:"allow_freeform,omitempty"`
	Fields        []Field  `json:"fields,omitempty"`
}

AskRequest is the broadcast payload — Question + a server-minted id used by both UI (in POST /answer) and the manager's pending map (to route the answer back).

type Asker ¶ added in v0.17.0

type Asker interface {
	Ask(q Question, done <-chan struct{}) (Answer, error)
}

Asker is the transport-agnostic ask contract. The in-process Manager implements it for the HTTP server; SocketAsker implements it for sibling processes (stdio MCP) by dialing the server's unix socket — same pattern as the gate binary dialing gate.sock, so an ask works from any local process without HTTP auth.

type Field ¶ added in v0.17.0

type Field struct {
	Key           string   `json:"key"`
	Label         string   `json:"label"`
	Type          string   `json:"type,omitempty"`
	Placeholder   string   `json:"placeholder,omitempty"`
	Value         string   `json:"value,omitempty"` // prefill; empty for secrets
	Required      bool     `json:"required,omitempty"`
	Help          string   `json:"help,omitempty"`
	Options       []Option `json:"options,omitempty"`        // choice/multi/dropdown
	AllowFreeform bool     `json:"allow_freeform,omitempty"` // add an "Other…" text box
}

Field is one question/input in a structured form ask. When Question.Fields is non-empty the UI renders a form modal instead of the plain option/freeform card, and the answer comes back as Answer.Values keyed by Field.Key.

Type drives the input widget:

• "choice" — Options as single-select rows (pick one)
• "multi" — Options as multi-select rows (pick many; the answer is a JSON-encoded array of the selected values)
• "rank" — Options drag-reordered; the answer is a JSON-encoded array of values in the user's chosen order
• "dropdown" — Options as a <select> (pick one, compact)
• "text" — free text input (default when no Options)
• "secret" — password input; plaintext handled server-side, never echoed to the agent
• "number" — numeric input

In a multi-question ask (Question.Fields), the UI renders each field as one step in a wizard the user pages through and can skip.

AllowFreeform on a choice/dropdown field adds an "Other…" text box so the user can answer outside the preset Options.

type Manager ¶

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

Manager owns the per-process pending-asks map. Concurrent-safe; caller is expected to wire OnRequest/OnResolved into the SSE broadcaster so the UI sees state changes.

func NewManager(opt Options) *Manager

func (m *Manager) Ask(q Question, done <-chan struct{}) (Answer, error)

func (m *Manager) PendingFor(sessionID string) []AskRequest

func (m *Manager) Resolve(requestID string, ans Answer) bool

type Option ¶

type Option struct {
	Label       string `json:"label"`
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
}

Option is one choice presented to the user. Label = what they see, Value = what gets returned to the agent, Description = optional secondary line shown under the label in the wizard.

type Options ¶

type Options struct {
	DefaultTimeout time.Duration
	OnRequest      func(AskRequest)
	OnResolved     func(sessionID, requestID string)
}

Options wires callbacks. Both are optional; nil = no broadcast.

type Question ¶

type Question struct {
	SessionID     string        `json:"session_id"`
	AgentName     string        `json:"agent_name,omitempty"`
	Question      string        `json:"question"`
	Options       []Option      `json:"options,omitempty"`
	AllowFreeform bool          `json:"allow_freeform,omitempty"`
	Fields        []Field       `json:"fields,omitempty"`
	Timeout       time.Duration `json:"-"`
}

Question is the input to Manager.Ask. Mirrors the MCP tool's input schema 1:1 so the handler can pass it through unchanged.

type SocketAsker ¶ added in v0.17.0

type SocketAsker struct {
	Path string
}

SocketAsker dials the server's askuser socket. Implements Asker so the MCP handlers can use it interchangeably with the in-process Manager. Construction is cheap and dial happens per Ask — the server may start or restart at any time relative to this process.

func (a *SocketAsker) Ask(q Question, done <-chan struct{}) (Answer, error)

type SocketServer ¶ added in v0.17.0

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

SocketServer accepts ask requests from sibling processes and resolves them through the wrapped Manager (pending map + SSE + web-UI answer — identical path to an in-process ask).

func ServeSocket(path string, mgr *Manager) (*SocketServer, error)

func (s *SocketServer) Close() error

func (s *SocketServer) SocketPath() string