question

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 18, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package question defines provider-neutral structured user questions.

Index

Constants

View Source 
const (
	// CatalogID is the application-owned provenance of ask_user.
	CatalogID = "coding.question"
	// ToolName is the provider-neutral structured user-question capability.
	ToolName = "ask_user"
	// TextToolName is the exact one-field recovery capability used after a
	// malformed structured question.
	TextToolName = "ask_user_text"
	// RejectionToolResult is the durable result of an explicit user cancellation.
	RejectionToolResult = "The user canceled this question without selecting an answer."
)

Variables

View Source 
var (
	// ErrNoPending means no durable ask_user call is awaiting a response.
	ErrNoPending = errors.New("coding question: no pending request")
	// ErrMismatch means a response does not identify the current request exactly.
	ErrMismatch = errors.New("coding question: request mismatch")
)
View Source 
var ErrInvalid = errors.New("coding question: invalid value")

ErrInvalid means a question schema or response violates the protocol.

Functions

func Digest 

func Digest(spec Spec) (string, error)

Digest returns the deterministic digest of one validated schema.

func RequestCount 

func RequestCount(request Request) int

RequestCount returns the number of user-visible decisions. A free-form fallback is one decision even though it has no structured options.

func ValidateCall 

func ValidateCall(info agent.ToolCallInfo) error

ValidateCall checks one question Tool call through the same strict decoder used by the pause owner. Plan flow uses it only to choose the bounded recovery phase; it never repairs arguments.

func ValidateRequest 

func ValidateRequest(request Request) error

ValidateRequest verifies identity and schema integrity.

func ValidateResolution 

func ValidateResolution(request Request, resolution Resolution) error

ValidateResolution verifies one exact response against its pending request.

func ValidateResolutionShape 

func ValidateResolutionShape(resolution Resolution) error

ValidateResolutionShape validates bounded content that does not require the pending request schema. Runtime still calls ValidateResolution before use.

func ValidateSpec 

func ValidateSpec(spec Spec) error

ValidateSpec validates the bounded model-supplied schema.

Types

type Answer 

type Answer struct {
	Selections []string `json:"selections,omitempty"`
	Custom     string   `json:"custom,omitempty"`
}

Answer resolves one question in its original request order.

type Controller 

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

Controller owns ask_user validation, pause reconciliation, and one-shot resolution. Its pending state is reconstructable from the durable Tool call.

func NewController 

func NewController(resolver Resolver) (*Controller, error)

NewController constructs one question coordinator.

func (*Controller) BeforeTool 

func (c *Controller) BeforeTool(_ context.Context, info agent.ToolCallInfo) agent.ToolDecision

BeforeTool validates ask_user arguments before pausing the Agent loop.

func (*Controller) Catalog 

func (c *Controller) Catalog() (*catalog.Catalog, error)

Catalog returns the exact local read-risk ask_user registration.

func (*Controller) Reconcile 

func (c *Controller) Reconcile(pending []ai.ToolCallPart) (*Request, error)

Reconcile derives the current question from durable pending Tool calls. Non-question calls are left for their owning coordinator.

func (*Controller) Reject 

func (c *Controller) Reject(requestID, schemaDigest string) error

Reject durably records an explicit cancellation as a Tool error.

func (*Controller) Resolve 

func (c *Controller) Resolve(resolution Resolution) error

Resolve validates and durably records one exact answer before clearing it.

type Option 

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

Option is one model-provided selectable answer.

type Question 

type Question struct {
	Header   string   `json:"header"`
	Question string   `json:"question"`
	Options  []Option `json:"options"`
	Multiple bool     `json:"multiple,omitempty"`
}

Question is one single- or multiple-select user question.

type Request 

type Request struct {
	ID           string      `json:"id"`
	ToolCallID   string      `json:"tool_call_id"`
	SchemaDigest string      `json:"schema_digest"`
	Kind         RequestKind `json:"kind,omitempty"`
	Prompt       string      `json:"prompt,omitempty"`
	Questions    []Question  `json:"questions"`
}

Request is one Runtime-owned pending structured question.

func CloneRequest 

func CloneRequest(request Request) Request

CloneRequest returns a fully detached Request.

func NewFreeformRequest 

func NewFreeformRequest(id, toolCallID, prompt string) (Request, error)

NewFreeformRequest binds one bounded direct prompt to Runtime and Tool-call identities. The prompt is application-owned when malformed fallback arguments cannot be trusted.

func NewRequest 

func NewRequest(id, toolCallID string, spec Spec) (Request, error)

NewRequest binds a validated schema to Runtime and Tool-call identities.

type RequestKind 

type RequestKind string

RequestKind distinguishes structured choices from a direct free-form response owned by the Runtime. 

const (
	// RequestStructured is the backward-compatible zero-value request kind.
	RequestStructured RequestKind = ""
	// RequestFreeform asks for one direct text response.
	RequestFreeform RequestKind = "freeform"
)

type Resolution 

type Resolution struct {
	RequestID    string   `json:"request_id"`
	SchemaDigest string   `json:"schema_digest"`
	Answers      []Answer `json:"answers,omitempty"`
	Chat         string   `json:"chat,omitempty"`
}

Resolution is either complete structured answers or one chat response.

func CloneResolution 

func CloneResolution(resolution Resolution) Resolution

CloneResolution returns a fully detached Resolution.

type Resolver 

type Resolver interface {
	ResolveToolCalls(...agent.ToolResolution) error
}

Resolver durably records one result for a pending Tool call.

type Spec 

type Spec struct {
	Questions []Question `json:"questions"`
}

Spec is the exact model-supplied ask_user argument shape.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.