agent

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

type AgentOption func(*Agent)

type Image struct {
	URL    string
	Base64 string
}

type ListenerFuncs struct {
	OnStartFunc     func(run *RunContext)
	OnSubscribeFunc func()
	OnModelFunc     func(model string)
	OnContentFunc   func(contentSoFar string)
	OnReasoningFunc func(reasoningSoFar string)
	OnUsageFunc     func(model string, usage *schema.TokenUsage)
	OnSubagentFunc  func(event SubagentEvent)
	// OnMessageQueuedFunc and OnQueuedMessageReadFunc observe FireOrQueue
	// joining messages to a run in flight.
	OnMessageQueuedFunc     func(requestID, display string)
	OnQueuedMessageReadFunc func(requestIDs []string)
	OnErrorFunc             func(err error)
	OnFinishedFunc          func(outcome Outcome)
	// ShouldContinueFunc nil means always continue.
	ShouldContinueFunc func() bool
}

type Outcome string

type Request struct {
	// RequestID is what Cancel stops; empty means not cancellable.
	RequestID string
	// ParentRequestID names the run that started this one, when it is a
	// subagent: cancelling the parent cancels this run, its tokens count on
	// the parent's turn, and the parent is held open until it finishes. A
	// parent that already ended is forgotten — there is nobody to tell.
	ParentRequestID string
	// Description is one line saying what the run is for, shown to listeners
	// of the parent run while a subagent works.
	Description string
	// Scenario is required (NewRequest's argument).
	Scenario Scenario
	UserID   string
	ChatID   string
	// ChatType defaults to "p2p".
	ChatType string
	// GroupID and TenantID scope the run's reads beyond the user's own
	// home: a group's or tenant's shared files and skills are read through
	// (never written to), and the knowledge base and sandbox carry the same
	// scope. Empty means no scope.
	GroupID  string
	TenantID string
	// SituationID is set by optional external-event triage runs. It is carried
	// to situation management tools and otherwise has no runtime meaning.
	SituationID string
	// ScheduledTaskID identifies the task whose firing is executing.
	ScheduledTaskID string
	// ConversationID groups the runs that share chat memory.
	ConversationID string
	RootMessageID  string
	ReplyMessageID string
	// Background runs post no answer of their own (see ScheduledTask).
	Background bool
	// PromptVariables extend the system prompt's variable set.
	PromptVariables map[string]string
	// Images may accompany Text.
	Images []Image
	// Listeners observe this run, alongside any application-level observers.
	Listeners []ResponseListener
	// TodoHandlers receive this run's todo updates.
	TodoHandlers []tools.TodoEventHandler

	// Text is the user message passed to the model.
	Text string
	// KnowledgeRetrieval is an explicit, fixed-scope lookup for unattended
	// runs. When nil, an attached knowledge base derives scope from identity and
	// retrieves using Text.
	KnowledgeRetrieval *knowledge.KnowledgeRetrieval
}

type RequestOption func(*Request)

type ResponseListener interface {
	OnStart(run *RunContext)
	OnSubscribe()
	OnModel(model string)
	OnContent(contentSoFar string)
	// OnReasoning receives the reasoning so far, accumulated like OnContent
	// but reset per model call: a run's thinking is one block per model call,
	// joined by a blank line, because a second call after a tool result is a
	// new line of thought, not a continuation of the first.
	OnReasoning(reasoningSoFar string)
	OnUsage(model string, usage *schema.TokenUsage)
	// OnSubagent reports what a run this one started is doing. Only the
	// parent's listeners receive it, and only the fields the event kind
	// carries — see SubagentEvent.
	OnSubagent(event SubagentEvent)
	// OnMessageQueued reports that a message joined this run in flight via
	// FireOrQueue and is waiting to be read at the next tool boundary.
	// Display names the message (a preview, a sender); it is identifying
	// prose, not the body.
	OnMessageQueued(requestID, display string)
	// OnQueuedMessageRead reports the request ids the run just read into
	// itself at a tool boundary — messages this run answers, so their
	// senders are not waiting on a run of their own.
	OnQueuedMessageRead(requestIDs []string)
	OnError(err error)
	// OnFinished is called exactly once, whatever the run ended by.
	OnFinished(outcome Outcome)
	// ShouldContinue is polled between model iterations; false ends the run as
	// cancelled. It is how a surface that stopped listening (a closed card,
	// say) stops the work that was feeding it.
	ShouldContinue() bool
}

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

type Scenario interface {
	// Name identifies the scenario in logs and surfaces.
	Name() string

	// ConversationMemory reports whether the run joins the conversation it
	// names — reads its history and appends to it. A run with no memory
	// still has an identity, but each one starts from nothing.
	ConversationMemory() bool

	// Offers decides whether a run of this scenario gets the named tool.
	// The default is everything; see ScheduledTaskScenario for the one
	// exception the runtime ships.
	Offers(toolName string) bool
}

type ScenarioBase struct{}

type SubagentEvent struct {
	SubagentID   string
	Description  string
	ContentSoFar string
	Model        string
	Usage        *schema.TokenUsage
	Outcome      Outcome
}