clarify

type AskClarifyingQuestionRequest struct {
	// Question is the question text shown to the user. Required.
	Question string `json:"question" jsonschema:"description=The question to ask the user. Be specific and concise.,required"`
	// Context is an optional explanation of why the LLM needs this
	// information, helping the user craft a better answer.
	Context string `` /* 133-byte string literal not displayed */
}

type ClarificationEvent struct {
	RequestID string // unique ID for this clarification, matches the DB row
	Question  string // the question text displayed to the user
	Context   string // optional LLM-provided context (may be empty)
}

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

type EventEmitter func(ctx context.Context, evt ClarificationEvent) error

type RecoverResult struct {
	Expired   int // questions older than maxAge, marked "expired" in the DB
	Recovered int // questions within maxAge, waiter channels re-registered for live use
}

type Request struct {
	ID       string `json:"id"`
	Question string `json:"question"`
	Context  string `json:"context,omitempty"` // optional LLM-provided context about why the question is needed
}

type Response struct {
	Answer string `json:"answer"`
}

type Store interface {
	// Ask creates a pending clarification request, persists it, and returns
	// the unique request ID together with a channel that will receive the
	// user's [Response] when [Respond] is called.
	//
	// Parameters:
	//   - question: the question text displayed to the user.
	//   - qContext: optional LLM-provided context explaining why the
	//     information is needed (may be empty).
	//   - senderContext: opaque platform-specific sender identifier
	//     (e.g. "slack:U1234:C5678") used for messenger routing and
	//     persisted so [RecoverPending] can replay questions.
	//
	// The returned channel is buffered (cap 1) so [Respond] never blocks.
	// The caller must eventually call [Cleanup] to release the channel.
	Ask(ctx context.Context, question, qContext, senderContext string) (string, <-chan Response, error)

	// Respond delivers the user's answer to the pending clarification
	// identified by id. It updates the persistent store and signals any
	// goroutine blocked in [WaitForResponse].
	//
	// Returns an error if id does not exist or was already answered.
	Respond(id, answer string) error

	// WaitForResponse blocks until the clarification identified by id is
	// answered or ctx is cancelled/expired. ch must be the channel returned
	// by [Ask] for the same id.
	//
	// The implementation uses a hybrid strategy: it listens on ch for
	// immediate notification from [Respond], and polls the database every
	// 5 seconds as a fallback (in case the channel signal was missed due
	// to a race with [Cleanup] or a server restart).
	WaitForResponse(ctx context.Context, id string, ch <-chan Response) (Response, error)

	// Cleanup removes the in-process waiter channel for the given request.
	// It should be called (typically via defer) after [WaitForResponse]
	// returns, whether the question was answered or timed out.
	Cleanup(id string)

	// FindPendingByQuestion returns the ID of an existing pending
	// clarification whose question text matches the given string.
	// Used for deduplication — both within a session and across sessions.
	// Returns ("", false) if no pending match is found.
	FindPendingByQuestion(ctx context.Context, question string) (string, bool)

	// RecoverPending handles clarifications left in "pending" state from
	// a previous server instance. Questions older than maxAge are marked
	// "expired"; recent ones get fresh waiter channels so they can still
	// be answered via the API.
	//
	// This should be called once at application startup, before the
	// AG-UI server begins accepting requests.
	RecoverPending(ctx context.Context, maxAge time.Duration) (RecoverResult, error)

	// Close releases any resources held by the store (e.g. in-memory
	// waiter channels). It does not close the underlying database.
	Close()
}

type ToolOption func(*askClarifyTool)

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