session

type AsyncToolCheckResult struct {
	// ShouldWait is true if the tool requires human approval before execution.
	ShouldWait bool
	// PendingInfo provides context when ShouldWait is true.
	PendingInfo *tools.PendingToolInfo
	// Handled is true when the checker executed the handler directly
	// (i.e., the tool was an async tool but the check passed, so it ran immediately).
	Handled bool
	// HandlerResult contains the JSON-encoded result when Handled is true.
	HandlerResult json.RawMessage
	// HandlerError is set when Handled is true but execution failed.
	HandlerError error
}

type AsyncToolChecker func(callID, name string, args map[string]any) *AsyncToolCheckResult

type BaseSession interface {
	// Identity
	ID() string

	// Variable management for template substitution
	Variables() map[string]string
	SetVar(name, value string)
	GetVar(name string) (string, bool)

	// State management - encapsulates StateStore access
	Messages(ctx context.Context) ([]types.Message, error)
	Clear(ctx context.Context) error
}

type DuplexSession interface {
	BaseSession

	// SendChunk sends a chunk to the session (populate MediaDelta for media, Content for text).
	// This method is thread-safe and can be called from multiple goroutines.
	SendChunk(ctx context.Context, chunk *providers.StreamChunk) error

	// SendText is a convenience method for sending text directly.
	SendText(ctx context.Context, text string) error

	// SendFrame sends an image frame to the session for realtime video scenarios.
	// This is a convenience method that wraps SendChunk with proper image formatting.
	SendFrame(ctx context.Context, frame *ImageFrame) error

	// SendVideoChunk sends a video chunk to the session for encoded video streaming.
	// This is a convenience method that wraps SendChunk with proper video formatting.
	SendVideoChunk(ctx context.Context, chunk *VideoChunk) error

	// Response returns a receive-only channel for streaming responses.
	// The channel emits StreamChunks containing LLM responses (text, media, tool calls, etc).
	Response() <-chan providers.StreamChunk

	// Close ends the streaming session and releases resources.
	Close() error

	// Drain gracefully stops the session: sends EndOfStream to the pipeline,
	// waits for the provider to finish processing (up to the given timeout),
	// then closes. Returns nil if the pipeline completes within the timeout.
	Drain(ctx context.Context) error

	// Done returns a channel that's closed when the session ends.
	Done() <-chan struct{}

	// Error returns any error that occurred during the session.
	Error() error

	// SubmitToolResults sends resolved/rejected tool results back into the
	// duplex pipeline so they flow to the provider via ToolResponseSupport.
	// Used after HITL approval or client tool fulfillment.
	SubmitToolResults(ctx context.Context, responses []providers.ToolResponse) error

	// ForkSession creates a new session that is a fork of this one.
	// The new session will have an independent copy of the conversation state.
	ForkSession(
		ctx context.Context,
		forkID string,
		pipelineBuilder PipelineBuilder,
	) (DuplexSession, error)
}

type DuplexSessionConfig struct {
	ConversationID   string
	UserID           string
	StateStore       statestore.Store                // StateStore for conversation history
	PipelineBuilder  PipelineBuilder                 // Function to build pipeline (required, typically a closure from SDK)
	Provider         providers.Provider              // Provider for LLM calls (required)
	Config           *providers.StreamingInputConfig // For ASM mode: base streaming config. For VAD mode: nil
	ToolRegistry     *tools.Registry                 // Optional: for executing tool calls
	AsyncToolChecker AsyncToolChecker                // Optional: HITL gate for tool calls
	Metadata         map[string]interface{}
	Variables        map[string]string // Initial variables for template substitution
}

type ImageFrame struct {
	// Data is the raw image data (JPEG, PNG, etc.)
	Data []byte

	// MIMEType is the MIME type of the image (e.g., "image/jpeg")
	MIMEType string

	// Width is the image width in pixels (optional, for metadata)
	Width int

	// Height is the image height in pixels (optional, for metadata)
	Height int

	// FrameNum is the sequence number for ordering frames
	FrameNum int64

	// Timestamp is when the frame was captured
	Timestamp time.Time
}

type PipelineBuilder func(
	ctx context.Context,
	provider providers.Provider,
	streamProvider providers.StreamInputSupport,
	streamConfig *providers.StreamingInputConfig,
	conversationID string,
	store statestore.Store,
) (*stage.StreamPipeline, error)

type UnarySession interface {
	BaseSession

	// Execution methods
	Execute(ctx context.Context, role, content string) (*pipeline.ExecutionResult, error)
	ExecuteWithMessage(ctx context.Context, message types.Message) (*pipeline.ExecutionResult, error)
	ExecuteStream(ctx context.Context, role, content string) (<-chan providers.StreamChunk, error)
	ExecuteStreamWithMessage(ctx context.Context, message types.Message) (<-chan providers.StreamChunk, error)

	// ResumeWithToolResults injects tool result messages into the session
	// history and re-executes the pipeline so the LLM can continue.
	ResumeWithToolResults(ctx context.Context, toolResults []types.Message) (*pipeline.ExecutionResult, error)

	// ResumeStreamWithToolResults is the streaming equivalent of ResumeWithToolResults.
	// It injects tool result messages and returns a streaming channel.
	ResumeStreamWithToolResults(ctx context.Context, toolResults []types.Message) (<-chan providers.StreamChunk, error)

	// ForkSession creates a new session that is a fork of this one.
	// The new session will have an independent copy of the conversation state.
	ForkSession(ctx context.Context, forkID string, pipeline *stage.StreamPipeline) (UnarySession, error)
}

type UnarySessionConfig struct {
	ConversationID string
	UserID         string
	StateStore     statestore.Store // Must match Pipeline's StateStore stages
	Pipeline       *stage.StreamPipeline
	Metadata       map[string]interface{}
	Variables      map[string]string // Initial variables for template substitution
}

type VideoChunk struct {
	// Data is the encoded video data (H.264, VP8, etc.)
	Data []byte

	// MIMEType is the MIME type of the video (e.g., "video/h264")
	MIMEType string

	// Width is the video width in pixels (optional, for metadata)
	Width int

	// Height is the video height in pixels (optional, for metadata)
	Height int

	// ChunkIndex is the sequence number for ordering chunks
	ChunkIndex int

	// IsKeyFrame indicates if this chunk contains a keyframe
	IsKeyFrame bool

	// Timestamp is when the chunk was created/captured
	Timestamp time.Time

	// Duration is the duration of this video chunk
	Duration time.Duration
}