runtime

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CoreControlAskUser      = tools.ControlAskUser
	CoreControlTaskComplete = tools.ControlTaskComplete
)
View Source 
const (
	ReasoningLevelDefault = config.ReasoningLevelDefault
	ReasoningLevelOff     = config.ReasoningLevelOff
	ReasoningLevelMinimal = config.ReasoningLevelMinimal
	ReasoningLevelLow     = config.ReasoningLevelLow
	ReasoningLevelMedium  = config.ReasoningLevelMedium
	ReasoningLevelHigh    = config.ReasoningLevelHigh
	ReasoningLevelXHigh   = config.ReasoningLevelXHigh
	ReasoningLevelMax     = config.ReasoningLevelMax
)
View Source 
const (
	FinishReasonUnknown       = observation.FinishReasonUnknown
	FinishReasonStop          = observation.FinishReasonStop
	FinishReasonToolCalls     = observation.FinishReasonToolCalls
	FinishReasonLength        = observation.FinishReasonLength
	FinishReasonContentFilter = observation.FinishReasonContentFilter
	FinishReasonError         = observation.FinishReasonError
	FinishReasonCancelled     = observation.FinishReasonCancelled

	CompletionReasonNaturalStop = observation.CompletionReasonNaturalStop
	CompletionReasonToolSignal  = observation.CompletionReasonToolSignal
	CompletionReasonHookStop    = observation.CompletionReasonHookStop

	ContinuationReasonToolResults       = observation.ContinuationReasonToolResults
	ContinuationReasonCompaction        = observation.ContinuationReasonCompaction
	ContinuationReasonProviderTruncated = observation.ContinuationReasonProviderTruncated
	ContinuationReasonRetryEmpty        = observation.ContinuationReasonRetryEmpty
	ContinuationReasonNoProgress        = observation.ContinuationReasonNoProgress
	ContinuationReasonHook              = observation.ContinuationReasonHook
)

Variables

View Source 
var (
	// ErrThreadNotFound reports that a durable thread requested through Host was not found.
	ErrThreadNotFound = errors.New("floret thread not found")
	// ErrTurnNotFound reports that a durable turn requested through Host was not found.
	ErrTurnNotFound = errors.New("floret turn not found")
	// ErrRunNotFound reports that a durable run requested through Host was not found.
	ErrRunNotFound = errors.New("floret run not found")
	// ErrSubAgentNotFound reports that a parent-scoped child thread requested through Host was not found.
	ErrSubAgentNotFound = errors.New("floret subagent not found")
	// ErrForkOperationConflict reports that an operation ID was reused with a different fork request.
	ErrForkOperationConflict = errors.New("floret fork operation conflicts with existing request")
	// ErrForkDestinationConflict reports that a planned destination is owned by another operation or node.
	ErrForkDestinationConflict = errors.New("floret fork destination conflicts with operation plan")
	// ErrForkOperationTargetMissing reports that a completed operation no longer has every marked target.
	ErrForkOperationTargetMissing = errors.New("floret fork operation target is missing")
	// ErrAgentTodoVersionConflict reports that a todo update was based on a stale canonical version.
	ErrAgentTodoVersionConflict = errors.New("floret agent todo version conflict")
	// ErrJournalInvariant reports an ambiguous active path that Floret refuses to repair heuristically.
	ErrJournalInvariant = errors.New("floret thread journal invariant violated")
)

Functions

func CoreControlDefinitions added in v0.3.10 

func CoreControlDefinitions(includeTaskComplete bool) []tools.ToolDefinition

CoreControlDefinitions returns product-neutral control signal tools for hosts that want Floret to own common ask-user/task-complete schema validation.

func ManualCompactionOperationID added in v0.3.33 

func ManualCompactionOperationID(runID RunID, step int, requestID string) string

ManualCompactionOperationID returns the Floret operation identity that links the start, debug, complete, and failed observations for a projected manual compaction at the given provider-loop step.

func ProviderSafeCoreControlText added in v0.3.10 

func ProviderSafeCoreControlText(signal TurnSignal) string

ProviderSafeCoreControlText returns provider-visible transcript text for product-neutral core control signals.

Types

type AgentTodo added in v0.11.0 

type AgentTodo struct {
	ID      string          `json:"id"`
	Content string          `json:"content"`
	Status  AgentTodoStatus `json:"status"`
}

type AgentTodoStatus added in v0.11.0 

type AgentTodoStatus string
const (
	AgentTodoPending    AgentTodoStatus = "pending"
	AgentTodoInProgress AgentTodoStatus = "in_progress"
	AgentTodoCompleted  AgentTodoStatus = "completed"
)

func (AgentTodoStatus) Valid added in v0.11.0 

func (s AgentTodoStatus) Valid() bool

type ArtifactRef added in v0.3.21 

type ArtifactRef struct {
	ID        string `json:"id,omitempty"`
	SafeLabel string `json:"safe_label,omitempty"`
	URL       string `json:"url,omitempty"`
	Kind      string `json:"kind,omitempty"`
	MIME      string `json:"mime,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	SHA256    string `json:"sha256,omitempty"`
}

type CapabilityOptions 

type CapabilityOptions struct {
	SkillsEnabled          bool
	SkillSources           []string
	SkillPromptBudgetBytes int
}

type CloseSubAgentRequest added in v0.3.17 

type CloseSubAgentRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	Reason         string
}

type CloseSubAgentsRequest added in v0.3.45 

type CloseSubAgentsRequest struct {
	ParentThreadID ThreadID
	Reason         string
}

type CloseSubAgentsResult added in v0.3.45 

type CloseSubAgentsResult struct {
	Snapshots []SubAgentSnapshot `json:"snapshots"`
	Closed    int                `json:"closed,omitempty"`
}

type CompactThreadRequest added in v0.3.37 

type CompactThreadRequest struct {
	ThreadID  ThreadID
	RequestID string
	Source    string
	Labels    RunLabels
	Limits    TurnLimits
	Reasoning ReasoningSelection
}

type CompactThreadResult added in v0.3.37 

type CompactThreadResult struct {
	ThreadID         ThreadID                     `json:"thread_id"`
	RunID            RunID                        `json:"run_id"`
	RequestID        string                       `json:"request_id"`
	Compaction       observation.CompactionEvent  `json:"compaction"`
	Metrics          RunMetrics                   `json:"metrics"`
	ActivityTimeline observation.ActivityTimeline `json:"activity_timeline"`
}

func (CompactThreadResult) Validate added in v0.10.0 

func (r CompactThreadResult) Validate() error

type CompletionReason added in v0.6.0 

type CompletionReason = observation.CompletionReason

type ContinuationReason added in v0.6.0 

type ContinuationReason = observation.ContinuationReason

type CreateThreadRequest added in v0.13.0 

type CreateThreadRequest struct {
	ThreadID ThreadID
}

type Event added in v0.3.0 

type Event struct {
	Type               observation.EventType             `json:"type"`
	TraceID            TraceID                           `json:"trace_id,omitempty"`
	RunID              RunID                             `json:"run_id,omitempty"`
	ThreadID           ThreadID                          `json:"thread_id,omitempty"`
	TurnID             TurnID                            `json:"turn_id,omitempty"`
	Step               int                               `json:"step,omitempty"`
	Provider           string                            `json:"provider,omitempty"`
	Model              string                            `json:"model,omitempty"`
	Message            string                            `json:"message,omitempty"`
	Result             string                            `json:"result,omitempty"`
	Error              string                            `json:"error,omitempty"`
	ToolID             string                            `json:"tool_id,omitempty"`
	ToolName           string                            `json:"tool_name,omitempty"`
	ToolKind           string                            `json:"tool_kind,omitempty"`
	ArgsHash           string                            `json:"args_hash,omitempty"`
	DurationMS         int64                             `json:"duration_ms,omitempty"`
	FinishReason       observation.FinishReason          `json:"finish_reason,omitempty"`
	RawFinishReason    string                            `json:"raw_finish_reason,omitempty"`
	FinishInferred     bool                              `json:"finish_inferred,omitempty"`
	CompletionReason   observation.CompletionReason      `json:"completion_reason,omitempty"`
	ContinuationReason observation.ContinuationReason    `json:"continuation_reason,omitempty"`
	Activity           *observation.ActivityPresentation `json:"activity,omitempty"`
	ActivityTimeline   *observation.ActivityTimeline     `json:"activity_timeline,omitempty"`
	Projection         *ThreadTurnProjection             `json:"projection,omitempty"`
	Stream             *StreamObservation                `json:"stream,omitempty"`
	Committed          *ThreadDetailEvent                `json:"committed,omitempty"`
	ContextStatus      *observation.ContextStatus        `json:"context_status,omitempty"`
	Compaction         *observation.CompactionEvent      `json:"compaction,omitempty"`
	CompactionDebug    *observation.CompactionDebugEvent `json:"compaction_debug,omitempty"`
	Sources            []SourceRef                       `json:"sources,omitempty"`
	Metadata           map[string]any                    `json:"metadata,omitempty"`
	Timestamp          time.Time                         `json:"timestamp,omitempty"`
}

func (Event) Validate added in v0.5.0 

func (e Event) Validate() error

type EventSink added in v0.3.0 

type EventSink interface {
	EmitEvent(Event)
}

type FinishReason added in v0.6.0 

type FinishReason = observation.FinishReason

type ForkOperationID added in v0.5.0 

type ForkOperationID string

type ForkThreadRequest added in v0.3.86 

type ForkThreadRequest struct {
	OperationID         ForkOperationID
	SourceThreadID      ThreadID
	DestinationThreadID ThreadID
}

type ForkThreadResult added in v0.3.86 

type ForkThreadResult struct {
	OperationID ForkOperationID `json:"operation_id"`
	Thread      ThreadSummary   `json:"thread"`
	Turns       []ForkedTurnRef `json:"turns,omitempty"`
}

type ForkedTurnRef added in v0.3.86 

type ForkedTurnRef struct {
	SourceTurnID      TurnID    `json:"source_turn_id,omitempty"`
	SourceRunID       RunID     `json:"source_run_id,omitempty"`
	DestinationTurnID TurnID    `json:"destination_turn_id,omitempty"`
	DestinationRunID  RunID     `json:"destination_run_id,omitempty"`
	CreatedAt         time.Time `json:"created_at,omitempty"`
}

type Host added in v0.3.0 

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

Host is the concrete public facade for provider-backed durable conversations. Callers that need substitution should declare a local interface containing only the methods used by that responsibility.

func NewHost added in v0.3.0 

func NewHost(opts HostOptions) (*Host, error)

func (*Host) CloseSubAgent added in v0.3.17 

func (h *Host) CloseSubAgent(ctx context.Context, req CloseSubAgentRequest) (SubAgentSnapshot, error)

func (*Host) CompactThread added in v0.3.37 

func (h *Host) CompactThread(ctx context.Context, req CompactThreadRequest) (CompactThreadResult, error)

func (*Host) CompletePendingTool added in v0.3.10 

func (h *Host) CompletePendingTool(ctx context.Context, req PendingToolCompletionRequest) (TurnResult, error)

func (*Host) ListPendingApprovals added in v0.3.46 

func (h *Host) ListPendingApprovals(ctx context.Context, req ListPendingApprovalsRequest) (PendingApprovals, error)

func (*Host) ListSubAgentActivityTimeline added in v0.3.44 

func (h *Host) ListSubAgentActivityTimeline(ctx context.Context, req ListSubAgentActivityTimelineRequest) (SubAgentActivityTimelineResult, error)

func (*Host) ListSubAgentDetailEvents added in v0.3.21 

func (h *Host) ListSubAgentDetailEvents(ctx context.Context, req ListSubAgentDetailEventsRequest) (SubAgentDetailEvents, error)

func (*Host) ListSubAgents added in v0.3.17 

func (h *Host) ListSubAgents(ctx context.Context, parentThreadID ThreadID) ([]SubAgentSnapshot, error)

func (*Host) ListThreadDetailEvents added in v0.3.42 

func (h *Host) ListThreadDetailEvents(ctx context.Context, req ListThreadDetailEventsRequest) (ThreadDetailEvents, error)

func (*Host) ListThreadTurns added in v0.11.0 

func (h *Host) ListThreadTurns(ctx context.Context, req ListThreadTurnsRequest) (ThreadTurnsPage, error)

func (*Host) ReadLatestThreadTurn added in v0.11.4 

func (h *Host) ReadLatestThreadTurn(ctx context.Context, threadID ThreadID) (ThreadTurnSnapshot, error)

func (*Host) ReadSubAgentDetail added in v0.3.21 

func (h *Host) ReadSubAgentDetail(ctx context.Context, req ReadSubAgentDetailRequest) (SubAgentDetail, error)

func (*Host) ReadThread added in v0.3.0 

func (h *Host) ReadThread(ctx context.Context, threadID ThreadID) (ThreadSnapshot, error)

func (*Host) ReadThreadAgentTodos added in v0.11.0 

func (h *Host) ReadThreadAgentTodos(ctx context.Context, threadID ThreadID) (ThreadAgentTodoState, error)

func (*Host) ReadThreadContext added in v0.10.0 

func (h *Host) ReadThreadContext(ctx context.Context, threadID ThreadID) (ThreadContextSnapshot, error)

func (*Host) ReadThreadOverview added in v0.12.0 

func (h *Host) ReadThreadOverview(ctx context.Context, threadID ThreadID) (ThreadOverview, error)

func (*Host) ReadTurnProjection added in v0.3.69 

func (h *Host) ReadTurnProjection(ctx context.Context, req ReadTurnProjectionRequest) (ThreadTurnProjection, error)

func (*Host) RetryTurn added in v0.3.0 

func (h *Host) RetryTurn(ctx context.Context, req RetryTurnRequest) (TurnResult, error)

func (*Host) RunTurn added in v0.3.0 

func (h *Host) RunTurn(ctx context.Context, req RunTurnRequest) (TurnResult, error)

func (*Host) SendSubAgentInput added in v0.3.17 

func (h *Host) SendSubAgentInput(ctx context.Context, req SendSubAgentInputRequest) (SubAgentSnapshot, error)

func (*Host) SettlePendingTool added in v0.3.54 

func (h *Host) SettlePendingTool(ctx context.Context, req PendingToolSettlementRequest) (PendingToolSettlementResult, error)

func (*Host) SpawnSubAgent added in v0.3.17 

func (h *Host) SpawnSubAgent(ctx context.Context, req SpawnSubAgentRequest) (SubAgentSnapshot, error)

func (*Host) UpdateThreadAgentTodos added in v0.11.0 

func (h *Host) UpdateThreadAgentTodos(ctx context.Context, req UpdateThreadAgentTodosRequest) (ThreadAgentTodoState, error)

func (*Host) WaitSubAgents added in v0.3.17 

func (h *Host) WaitSubAgents(ctx context.Context, req WaitSubAgentsRequest) (WaitSubAgentsResult, error)

type HostOptions added in v0.3.0 

type HostOptions struct {
	Config               config.Config
	ModelGateway         ModelGateway
	ModelGatewayIdentity ModelGatewayIdentity
	Runtime              *HostRuntime
	Tools                *tools.Registry
	Approver             tools.Approver
	Sink                 EventSink
	ToolSurfaceProvider  ToolSurfaceProvider
	IDGenerator          func(string) string
	LoopLimits           LoopLimits
	SubAgentRunTimeout   time.Duration
	Capabilities         CapabilityOptions
	ThreadTitleMode      ThreadTitleMode
}

type HostRuntime added in v0.15.0 

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

HostRuntime is the opaque durable runtime capability accepted by NewHost and capability constructors. It has no exported methods; bootstrap code should use it only to construct the selected narrow handles and must not pass it to long-lived coordinators.

func NewHostRuntime added in v0.15.0 

func NewHostRuntime(store *Store) (*HostRuntime, error)

type HostedToolDefinition added in v0.3.40 

type HostedToolDefinition struct {
	Name        string         `json:"name"`
	Type        string         `json:"type"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Options     map[string]any `json:"options,omitempty"`
}

type ListPendingApprovalsRequest added in v0.3.46 

type ListPendingApprovalsRequest struct {
	ThreadID ThreadID
}

type ListSubAgentActivityTimelineRequest added in v0.3.44 

type ListSubAgentActivityTimelineRequest struct {
	ParentThreadID ThreadID
	Meta           observation.ActivityRunMeta
}

type ListSubAgentDetailEventsRequest added in v0.3.21 

type ListSubAgentDetailEventsRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	AfterOrdinal   int64
	Limit          int
	IncludeRaw     bool
}

type ListThreadDetailEventsRequest added in v0.3.42 

type ListThreadDetailEventsRequest struct {
	ThreadID     ThreadID
	AfterOrdinal int64
	Limit        int
	IncludeRaw   bool
}

type ListThreadTurnsRequest added in v0.11.0 

type ListThreadTurnsRequest struct {
	ThreadID      ThreadID `json:"thread_id"`
	BeforeOrdinal int64    `json:"before_ordinal,omitempty"`
	AfterOrdinal  int64    `json:"after_ordinal,omitempty"`
	Tail          int      `json:"tail,omitempty"`
	Limit         int      `json:"limit,omitempty"`
}

type LoopLimits added in v0.3.0 

type LoopLimits struct {
	MaxEmptyProviderRetries int
	NoProgressLimit         int
	DuplicateToolLimit      int
	WallTime                time.Duration
}

type ManualCompactionPollRequest added in v0.3.27 

type ManualCompactionPollRequest struct {
	RunID         RunID         `json:"run_id,omitempty"`
	ThreadID      ThreadID      `json:"thread_id,omitempty"`
	TurnID        TurnID        `json:"turn_id,omitempty"`
	TraceID       TraceID       `json:"trace_id,omitempty"`
	PromptScopeID PromptScopeID `json:"prompt_scope_id,omitempty"`
	Step          int           `json:"step,omitempty"`
}

type ManualCompactionRequest added in v0.3.27 

type ManualCompactionRequest struct {
	RequestID   string    `json:"request_id"`
	Source      string    `json:"source"`
	RequestedAt time.Time `json:"requested_at,omitempty"`
}

type ManualCompactionSource added in v0.3.27 

type ManualCompactionSource interface {
	PollManualCompaction(context.Context, ManualCompactionPollRequest) (ManualCompactionRequest, bool, error)
}

type MessageAttachment added in v0.12.0 

type MessageAttachment struct {
	ResourceRef string `json:"resource_ref"`
	Name        string `json:"name"`
	MIMEType    string `json:"mime_type"`
	SizeBytes   int64  `json:"size_bytes,omitempty"`
}

MessageAttachment identifies one host-owned resource attached to a durable user message. ResourceRef is opaque to Floret and is resolved only by the host's ModelGateway implementation.

func (MessageAttachment) Validate added in v0.12.0 

func (a MessageAttachment) Validate() error

type ModelEvent added in v0.3.1 

type ModelEvent struct {
	Type           ModelEventType       `json:"type"`
	Text           string               `json:"text,omitempty"`
	ToolCallStream *ModelToolCallStream `json:"tool_call_stream,omitempty"`
	ToolCalls      []tools.ToolCall     `json:"tool_calls,omitempty"`
	Sources        []SourceRef          `json:"sources,omitempty"`
	Reason         string               `json:"reason,omitempty"`
	Usage          ProviderUsage        `json:"usage,omitempty"`
	ResponseID     string               `json:"response_id,omitempty"`
	ResponseState  *ModelState          `json:"response_state,omitempty"`
	Err            error                `json:"-"`
}

ModelEvent carries streamed model output.

type ModelEventType added in v0.3.1 

type ModelEventType string

ModelEventType is a streamed model event kind. 

const (
	ModelEventDelta         ModelEventType = "delta"
	ModelEventReasoning     ModelEventType = "reasoning"
	ModelEventToolCallStart ModelEventType = "tool_call_start"
	ModelEventToolCallDelta ModelEventType = "tool_call_delta"
	ModelEventToolCallEnd   ModelEventType = "tool_call_end"
	ModelEventToolCalls     ModelEventType = "tool_calls"
	ModelEventUsage         ModelEventType = "usage"
	ModelEventSources       ModelEventType = "sources"
	ModelEventDone          ModelEventType = "done"
	ModelEventEmpty         ModelEventType = "empty"
	ModelEventTruncated     ModelEventType = "truncated"
	ModelEventError         ModelEventType = "error"
)

type ModelGateway added in v0.3.1 

type ModelGateway interface {
	StreamModel(context.Context, ModelRequest) (<-chan ModelEvent, error)
}

ModelGateway lets a host supply model access while Floret still owns the agent loop, tool dispatch, context pressure, and runtime ledgers.

type ModelGatewayIdentity added in v0.3.71 

type ModelGatewayIdentity struct {
	Provider              string
	Model                 string
	StateCompatibilityKey string
}

ModelGatewayIdentity names the host-owned model transport used by a ModelGateway-backed Host.

type ModelMessage added in v0.3.1 

type ModelMessage struct {
	Role        ModelMessageRole    `json:"role"`
	Text        string              `json:"text,omitempty"`
	Attachments []MessageAttachment `json:"attachments,omitempty"`
	Reasoning   string              `json:"reasoning,omitempty"`
	ToolCalls   []tools.ToolCall    `json:"tool_calls,omitempty"`
	ToolResult  *ModelToolResult    `json:"tool_result,omitempty"`
}

ModelMessage is one validated provider-visible message generated by Floret.

func (ModelMessage) Validate added in v0.10.0 

func (m ModelMessage) Validate() error

type ModelMessageRole added in v0.10.0 

type ModelMessageRole string
const (
	ModelMessageRoleSystem    ModelMessageRole = "system"
	ModelMessageRoleUser      ModelMessageRole = "user"
	ModelMessageRoleAssistant ModelMessageRole = "assistant"
	ModelMessageRoleTool      ModelMessageRole = "tool"
)

func (ModelMessageRole) Valid added in v0.10.0 

func (r ModelMessageRole) Valid() bool

type ModelRequest added in v0.3.1 

type ModelRequest struct {
	RunID           RunID
	ThreadID        ThreadID
	TurnID          TurnID
	TraceID         TraceID
	PromptScopeID   PromptScopeID
	Step            int
	Provider        string
	Model           string
	Messages        []ModelMessage
	Tools           []tools.ToolDefinition
	HostedTools     []HostedToolDefinition
	MaxOutputTokens int64
	Reasoning       ReasoningSelection
	PreviousState   *ModelState
	Labels          RunLabels
}

ModelRequest is the host-safe model request shape passed to ModelGateway.

type ModelState added in v0.3.1 

type ModelState struct {
	Kind       string            `json:"kind,omitempty"`
	ID         string            `json:"id,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

ModelState is opaque provider continuation state. A ModelGateway interprets the provider-specific envelope; Floret owns its cross-turn persistence.

type ModelToolCallStream added in v0.3.16 

type ModelToolCallStream struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

ModelToolCallStream identifies a tool call while the model is still generating it. The final executable tool calls are delivered separately by ModelEventToolCalls.

type ModelToolResult added in v0.10.0 

type ModelToolResult struct {
	CallID   string `json:"call_id"`
	ToolName string `json:"tool_name"`
	Text     string `json:"text,omitempty"`
}

type PendingApproval added in v0.3.46 

type PendingApproval struct {
	ApprovalID  string                    `json:"approval_id,omitempty"`
	ToolCallID  string                    `json:"tool_call_id,omitempty"`
	ToolName    string                    `json:"tool_name,omitempty"`
	ToolKind    string                    `json:"tool_kind,omitempty"`
	RunID       RunID                     `json:"run_id,omitempty"`
	ThreadID    ThreadID                  `json:"thread_id,omitempty"`
	TurnID      TurnID                    `json:"turn_id,omitempty"`
	Step        int                       `json:"step,omitempty"`
	BatchIndex  int                       `json:"batch_index"`
	BatchSize   int                       `json:"batch_size"`
	State       string                    `json:"state,omitempty"`
	Revision    int64                     `json:"revision,omitempty"`
	Epoch       int64                     `json:"epoch,omitempty"`
	RequestedAt time.Time                 `json:"requested_at,omitempty"`
	ResolvedAt  time.Time                 `json:"resolved_at,omitempty"`
	ArgsHash    string                    `json:"args_hash,omitempty"`
	Resources   []PendingApprovalResource `json:"resources,omitempty"`
	Effects     []string                  `json:"effects,omitempty"`
	Labels      map[string]string         `json:"labels,omitempty"`
	HostContext map[string]string         `json:"host_context,omitempty"`
	ReadOnly    bool                      `json:"read_only,omitempty"`
	Destructive bool                      `json:"destructive,omitempty"`
	OpenWorld   bool                      `json:"open_world,omitempty"`
	Reason      string                    `json:"reason,omitempty"`
}

func (PendingApproval) Validate added in v0.11.4 

func (p PendingApproval) Validate() error

type PendingApprovalResource added in v0.3.46 

type PendingApprovalResource struct {
	Kind  string `json:"kind,omitempty"`
	Value string `json:"value,omitempty"`
}

func (PendingApprovalResource) Validate added in v0.11.4 

func (r PendingApprovalResource) Validate() error

type PendingApprovals added in v0.3.46 

type PendingApprovals struct {
	ThreadID    ThreadID          `json:"thread_id"`
	Approvals   []PendingApproval `json:"approvals"`
	GeneratedAt time.Time         `json:"generated_at"`
}

func (PendingApprovals) Validate added in v0.11.4 

func (p PendingApprovals) Validate() error

type PendingToolCompletionRequest added in v0.3.10 

type PendingToolCompletionRequest struct {
	ThreadID   ThreadID
	TurnID     TurnID
	RunID      RunID
	ToolCallID string
	ToolName   string
	Handle     string
	Status     PendingToolCompletionStatus
	Summary    string
	Output     string
	Labels     RunLabels
}

PendingToolCompletionRequest asks Floret to append a host-authored follow-up turn for work whose lifecycle was owned outside Floret.

type PendingToolCompletionStatus added in v0.3.10 

type PendingToolCompletionStatus string

PendingToolCompletionStatus describes the observed outcome of host-owned work that was previously exposed to the agent as a pending tool result. 

const (
	PendingToolCompletionCompleted PendingToolCompletionStatus = "completed"
	PendingToolCompletionFailed    PendingToolCompletionStatus = "failed"
	PendingToolCompletionCanceled  PendingToolCompletionStatus = "canceled"
)

type PendingToolSettlementHost added in v0.15.0 

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

PendingToolSettlementHost is the provider-free capability for settling host-owned pending tool work. It is not a general maintenance facade; the host must bind one instance to the coordinator that owns that settlement.

func NewPendingToolSettlementHost added in v0.15.0 

func NewPendingToolSettlementHost(opts ThreadCapabilityOptions) (*PendingToolSettlementHost, error)

func (*PendingToolSettlementHost) SettlePendingTool added in v0.15.0 

func (h *PendingToolSettlementHost) SettlePendingTool(ctx context.Context, req PendingToolSettlementRequest) (PendingToolSettlementResult, error)

type PendingToolSettlementRequest added in v0.3.54 

type PendingToolSettlementRequest struct {
	Target   PendingToolSettlementTarget
	Status   PendingToolSettlementStatus
	Summary  string
	Output   string
	Activity *observation.ActivityPresentation
}

PendingToolSettlementRequest records a host-owned pending tool outcome as a detail/activity event only. It does not resume the provider loop.

type PendingToolSettlementResult added in v0.3.54 

type PendingToolSettlementResult struct {
	Target                 PendingToolSettlementTarget `json:"target"`
	Event                  ThreadDetailEvent           `json:"event"`
	ProjectionAvailability TurnProjectionAvailability  `json:"projection_availability"`
	Projection             *ThreadTurnProjection       `json:"projection,omitempty"`
	ProjectionError        string                      `json:"projection_error,omitempty"`
}

func (PendingToolSettlementResult) Validate added in v0.10.0 

func (r PendingToolSettlementResult) Validate() error

type PendingToolSettlementStatus added in v0.3.54 

type PendingToolSettlementStatus string

PendingToolSettlementStatus describes a host-owned pending tool outcome that should update Floret activity without adding provider-visible context. 

const (
	PendingToolSettlementCompleted PendingToolSettlementStatus = "completed"
	PendingToolSettlementFailed    PendingToolSettlementStatus = "failed"
	PendingToolSettlementCanceled  PendingToolSettlementStatus = "canceled"
)

type PendingToolSettlementTarget added in v0.9.0 

type PendingToolSettlementTarget struct {
	ThreadID   ThreadID `json:"thread_id"`
	TurnID     TurnID   `json:"turn_id"`
	RunID      RunID    `json:"run_id"`
	ToolCallID string   `json:"tool_call_id"`
	ToolName   string   `json:"tool_name"`
	Handle     string   `json:"handle"`
}

PendingToolSettlementTarget identifies the exact pending tool result that a host owns and intends to settle.

type ProjectThreadTurnRequest added in v0.3.49 

type ProjectThreadTurnRequest struct {
	ThreadID ThreadID
	TurnID   TurnID
	RunID    RunID
	TraceID  TraceID
	Events   []ThreadDetailEvent
}

type PromptScopeID added in v0.3.0 

type PromptScopeID string

type ProviderUsage added in v0.3.1 

type ProviderUsage struct {
	InputTokens       int64   `json:"input_tokens,omitempty"`
	OutputTokens      int64   `json:"output_tokens,omitempty"`
	ReasoningTokens   int64   `json:"reasoning_tokens,omitempty"`
	CacheReadTokens   int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens  int64   `json:"cache_write_tokens,omitempty"`
	TotalTokens       int64   `json:"total_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
	Source            string  `json:"source,omitempty"`
	Available         bool    `json:"available,omitempty"`
	WindowInputTokens int64   `json:"window_input_tokens,omitempty"`
}

ProviderUsage is normalized provider token and cost usage.

type ReadSubAgentDetailRequest added in v0.3.21 

type ReadSubAgentDetailRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	AfterOrdinal   int64
	Limit          int
	IncludeRaw     bool
}

type ReadTurnProjectionRequest added in v0.3.69 

type ReadTurnProjectionRequest struct {
	ThreadID ThreadID
	TurnID   TurnID
	RunID    RunID
}

ReadTurnProjectionRequest identifies a durable hosted turn projection to rebuild from Floret detail. RunID is required and must match the execution identity recorded for the turn.

type ReasoningBudget added in v0.3.19 

type ReasoningBudget = config.ReasoningBudget

type ReasoningCapability added in v0.3.19 

type ReasoningCapability = config.ReasoningCapability

type ReasoningLevel added in v0.3.19 

type ReasoningLevel = config.ReasoningLevel

type ReasoningSelection added in v0.3.19 

type ReasoningSelection = config.ReasoningSelection

type RetryTurnRequest added in v0.3.0 

type RetryTurnRequest struct {
	ThreadID ThreadID
	Reason   string
	Labels   RunLabels
}

type RunID added in v0.3.0 

type RunID string

type RunLabels added in v0.3.0 

type RunLabels struct {
	Correlation map[string]string
	Host        map[string]string
}

type RunMetrics added in v0.3.1 

type RunMetrics struct {
	ProviderUsage ProviderUsage `json:"provider_usage"`
	Steps         int           `json:"steps"`
	LLMRequests   int           `json:"llm_requests"`
	ToolCalls     int           `json:"tool_calls"`
	Compactions   int           `json:"compactions"`
	Retries       int           `json:"retries"`
	WallTimeMS    int64         `json:"wall_time_ms,omitempty"`
}

RunMetrics summarizes the observable work completed by a run.

type RunTurnRequest added in v0.3.0 

type RunTurnRequest struct {
	RunID               RunID
	ThreadID            ThreadID
	TurnID              TurnID
	Input               TurnInput
	SupplementalContext []TurnSupplementalContextItem
	Labels              RunLabels
	Completion          TurnCompletionPolicy
	Signals             TurnSignalSpec
	Limits              TurnLimits
	Reasoning           ReasoningSelection
	ManualCompactions   ManualCompactionSource
	ToolSurfaceProvider ToolSurfaceProvider
}

type SendSubAgentInputRequest added in v0.3.17 

type SendSubAgentInputRequest struct {
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	Message        string
	Interrupt      bool
	Labels         RunLabels
}

type SetThreadTitleRequest added in v0.12.0 

type SetThreadTitleRequest struct {
	ThreadID ThreadID `json:"thread_id"`
	Title    string   `json:"title"`
}

type SignalDisposition added in v0.3.1 

type SignalDisposition string

SignalDisposition describes how a projected turn signal affects the run. 

const (
	// SignalContinue returns a provider-visible tool result and continues.
	SignalContinue SignalDisposition = "continue"
	// SignalWaiting pauses the run for host or user input.
	SignalWaiting SignalDisposition = "waiting"
	// SignalTerminal completes the run with the projected signal.
	SignalTerminal SignalDisposition = "terminal"
)

type SourceRef added in v0.3.13 

type SourceRef struct {
	Title string `json:"title,omitempty"`
	URL   string `json:"url,omitempty"`
}

type SpawnSubAgentRequest added in v0.3.17 

type SpawnSubAgentRequest struct {
	ParentThreadID  ThreadID
	ParentTurnID    TurnID
	ThreadID        ThreadID
	TaskName        string
	TaskDescription string
	Message         string
	HostProfileRef  string
	ForkMode        SubAgentForkMode
	Labels          RunLabels
}

type Store added in v0.3.0 

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

func NewMemoryStore added in v0.3.0 

func NewMemoryStore() *Store

func OpenSQLiteStore added in v0.3.0 

func OpenSQLiteStore(path string) (*Store, error)

func (*Store) Close added in v0.3.0 

func (s *Store) Close() error

type StreamObservation added in v0.3.10 

type StreamObservation struct {
	Type            StreamObservationType    `json:"type"`
	Text            string                   `json:"text,omitempty"`
	ToolCallStream  *ModelToolCallStream     `json:"tool_call_stream,omitempty"`
	Reason          string                   `json:"reason,omitempty"`
	FinishReason    observation.FinishReason `json:"finish_reason,omitempty"`
	RawFinishReason string                   `json:"raw_finish_reason,omitempty"`
	FinishInferred  bool                     `json:"finish_inferred,omitempty"`
	Attempt         int                      `json:"attempt,omitempty"`
	Labels          RunLabels                `json:"labels,omitempty"`
}

StreamObservation is a provider-neutral, engine-confirmed streaming fact for hosts that render live assistant output from Floret runtime events.

func (StreamObservation) Validate added in v0.7.0 

func (s StreamObservation) Validate() error

type StreamObservationType added in v0.3.10 

type StreamObservationType string
const (
	StreamObservationAssistantDelta   StreamObservationType = "assistant_delta"
	StreamObservationReasoningDelta   StreamObservationType = "reasoning_delta"
	StreamObservationToolCallStart    StreamObservationType = "tool_call_start"
	StreamObservationToolCallDelta    StreamObservationType = "tool_call_delta"
	StreamObservationToolCallEnd      StreamObservationType = "tool_call_end"
	StreamObservationModelRetry       StreamObservationType = "model_retry"
	StreamObservationModelStreamDone  StreamObservationType = "model_stream_done"
	StreamObservationModelStreamAbort StreamObservationType = "model_stream_abort"
)

func (StreamObservationType) Valid added in v0.7.0 

func (t StreamObservationType) Valid() bool

type SubAgentActivityTimelineResult added in v0.3.44 

type SubAgentActivityTimelineResult struct {
	Timeline    observation.ActivityTimeline `json:"activity_timeline"`
	GeneratedAt time.Time                    `json:"generated_at"`
}

type SubAgentDetail added in v0.3.21 

type SubAgentDetail struct {
	Snapshot         SubAgentSnapshot             `json:"snapshot"`
	Events           []ThreadDetailEvent          `json:"events"`
	ActivityTimeline observation.ActivityTimeline `json:"activity_timeline"`
	Context          ThreadContextSnapshot        `json:"context,omitempty"`
	NextOrdinal      int64                        `json:"next_ordinal,omitempty"`
	HasMore          bool                         `json:"has_more,omitempty"`
	RetainedFrom     int64                        `json:"retained_from,omitempty"`
	GeneratedAt      time.Time                    `json:"generated_at"`
}

type SubAgentDetailEvents added in v0.3.21 

type SubAgentDetailEvents struct {
	Events           []ThreadDetailEvent          `json:"events"`
	ActivityTimeline observation.ActivityTimeline `json:"activity_timeline"`
	Context          ThreadContextSnapshot        `json:"context,omitempty"`
	NextOrdinal      int64                        `json:"next_ordinal,omitempty"`
	HasMore          bool                         `json:"has_more,omitempty"`
	RetainedFrom     int64                        `json:"retained_from,omitempty"`
	GeneratedAt      time.Time                    `json:"generated_at"`
}

type SubAgentForkMode added in v0.3.17 

type SubAgentForkMode string
const (
	SubAgentForkNone     SubAgentForkMode = "none"
	SubAgentForkFullPath SubAgentForkMode = "full_path"
)

type SubAgentMaintenanceHost added in v0.15.0 

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

SubAgentMaintenanceHost closes unfinished child threads as one maintenance operation.

func NewSubAgentMaintenanceHost added in v0.15.0 

func NewSubAgentMaintenanceHost(opts ThreadCapabilityOptions) (*SubAgentMaintenanceHost, error)

func (*SubAgentMaintenanceHost) CloseSubAgents added in v0.15.0 

func (h *SubAgentMaintenanceHost) CloseSubAgents(ctx context.Context, req CloseSubAgentsRequest) (CloseSubAgentsResult, error)

type SubAgentSnapshot added in v0.3.17 

type SubAgentSnapshot struct {
	ThreadID        ThreadID         `json:"thread_id"`
	Path            string           `json:"path"`
	TaskName        string           `json:"task_name"`
	TaskDescription string           `json:"task_description,omitempty"`
	ParentThreadID  ThreadID         `json:"parent_thread_id"`
	ParentTurnID    TurnID           `json:"parent_turn_id,omitempty"`
	HostProfileRef  string           `json:"host_profile_ref,omitempty"`
	ForkMode        SubAgentForkMode `json:"fork_mode,omitempty"`
	Status          SubAgentStatus   `json:"status"`
	LatestTurnID    TurnID           `json:"latest_turn_id,omitempty"`
	LastMessage     string           `json:"last_message,omitempty"`
	WaitingPrompt   string           `json:"waiting_prompt,omitempty"`
	QueuedInputs    int              `json:"queued_inputs,omitempty"`
	CreatedAt       time.Time        `json:"created_at"`
	UpdatedAt       time.Time        `json:"updated_at"`
	Closed          bool             `json:"closed,omitempty"`
	CanSendInput    bool             `json:"can_send_input"`
	CanInterrupt    bool             `json:"can_interrupt"`
	CanClose        bool             `json:"can_close"`
}

type SubAgentStatus added in v0.3.17 

type SubAgentStatus string
const (
	SubAgentStatusIdle        SubAgentStatus = "idle"
	SubAgentStatusRunning     SubAgentStatus = "running"
	SubAgentStatusWaiting     SubAgentStatus = "waiting"
	SubAgentStatusCompleted   SubAgentStatus = "completed"
	SubAgentStatusFailed      SubAgentStatus = "failed"
	SubAgentStatusCancelled   SubAgentStatus = "cancelled"
	SubAgentStatusInterrupted SubAgentStatus = "interrupted"
	SubAgentStatusClosed      SubAgentStatus = "closed"
)

type ThreadAgentTodoState added in v0.11.0 

type ThreadAgentTodoState struct {
	ThreadID          ThreadID    `json:"thread_id"`
	Version           int64       `json:"version"`
	Items             []AgentTodo `json:"items"`
	UpdatedAt         time.Time   `json:"updated_at,omitempty"`
	UpdatedByTurnID   TurnID      `json:"updated_by_turn_id,omitempty"`
	UpdatedByRunID    RunID       `json:"updated_by_run_id,omitempty"`
	UpdatedByToolCall string      `json:"updated_by_tool_call_id,omitempty"`
}

type ThreadCapabilityOptions added in v0.15.0 

type ThreadCapabilityOptions struct {
	Runtime *HostRuntime
	Sink    EventSink
}

ThreadCapabilityOptions configures one narrow capability from an opaque runtime. Callers should construct these handles at bootstrap and pass only the selected handle to the coordinator that owns the corresponding lifecycle transition.

type ThreadContextSnapshot added in v0.10.0 

type ThreadContextSnapshot struct {
	ThreadID    ThreadID                      `json:"thread_id"`
	Provider    string                        `json:"provider,omitempty"`
	Model       string                        `json:"model,omitempty"`
	Policy      config.ContextPolicy          `json:"policy,omitempty"`
	Usage       *observation.ContextStatus    `json:"usage,omitempty"`
	Compactions []observation.CompactionEvent `json:"compactions,omitempty"`
	UpdatedAt   time.Time                     `json:"updated_at,omitempty"`
}

func (ThreadContextSnapshot) Validate added in v0.10.0 

func (s ThreadContextSnapshot) Validate() error

type ThreadControlSignal added in v0.11.0 

type ThreadControlSignal struct {
	Name        string         `json:"name"`
	CallID      string         `json:"call_id"`
	Disposition string         `json:"disposition,omitempty"`
	Text        string         `json:"text,omitempty"`
	ArgsHash    string         `json:"args_hash,omitempty"`
	Payload     map[string]any `json:"payload,omitempty"`
}

type ThreadCreateHost added in v0.15.0 

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

ThreadCreateHost is the coordinator capability that creates a canonical thread.

func NewThreadCreateHost added in v0.15.0 

func NewThreadCreateHost(opts ThreadCapabilityOptions) (*ThreadCreateHost, error)

func (*ThreadCreateHost) CreateThread added in v0.15.0 

func (h *ThreadCreateHost) CreateThread(ctx context.Context, req CreateThreadRequest) (ThreadSummary, error)

type ThreadDeleteHost added in v0.15.0 

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

ThreadDeleteHost is the coordinator capability that deletes a canonical thread tree.

func NewThreadDeleteHost added in v0.15.0 

func NewThreadDeleteHost(opts ThreadCapabilityOptions) (*ThreadDeleteHost, error)

func (*ThreadDeleteHost) DeleteThread added in v0.15.0 

func (h *ThreadDeleteHost) DeleteThread(ctx context.Context, threadID ThreadID) error

type ThreadDetailApproval added in v0.3.42 

type ThreadDetailApproval struct {
	State    string            `json:"state,omitempty"`
	ToolID   string            `json:"tool_id,omitempty"`
	ToolName string            `json:"tool_name,omitempty"`
	ToolKind string            `json:"tool_kind,omitempty"`
	ArgsHash string            `json:"args_hash,omitempty"`
	Reason   string            `json:"reason,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ThreadDetailCompaction added in v0.3.42 

type ThreadDetailCompaction struct {
	OperationID             string            `json:"operation_id,omitempty"`
	RequestID               string            `json:"request_id,omitempty"`
	Source                  string            `json:"source,omitempty"`
	CompactionID            string            `json:"compaction_id,omitempty"`
	PreviousCompactionID    string            `json:"previous_compaction_id,omitempty"`
	CompactedThroughEntryID string            `json:"compacted_through_entry_id,omitempty"`
	SummarySchemaVersion    string            `json:"summary_schema_version,omitempty"`
	CompactionGeneration    int               `json:"compaction_generation,omitempty"`
	CompactionWindowID      string            `json:"compaction_window_id,omitempty"`
	FirstKeptEntryID        string            `json:"first_kept_entry_id,omitempty"`
	KeptUserEntryIDs        []string          `json:"kept_user_entry_ids,omitempty"`
	Summary                 string            `json:"summary,omitempty"`
	Trigger                 string            `json:"trigger,omitempty"`
	Reason                  string            `json:"reason,omitempty"`
	Phase                   string            `json:"phase,omitempty"`
	TokensBefore            int64             `json:"tokens_before,omitempty"`
	TokensAfterEstimate     int64             `json:"tokens_after_estimate,omitempty"`
	Metadata                map[string]string `json:"metadata,omitempty"`
}

type ThreadDetailControlSignal added in v0.11.0 

type ThreadDetailControlSignal struct {
	Name        string         `json:"name,omitempty"`
	CallID      string         `json:"call_id,omitempty"`
	Disposition string         `json:"disposition,omitempty"`
	Text        string         `json:"text,omitempty"`
	ArgsHash    string         `json:"args_hash,omitempty"`
	Payload     map[string]any `json:"payload,omitempty"`
}

type ThreadDetailEvent added in v0.3.42 

type ThreadDetailEvent struct {
	ID        string                `json:"id"`
	Ordinal   int64                 `json:"ordinal"`
	ParentID  string                `json:"parent_id,omitempty"`
	ThreadID  ThreadID              `json:"thread_id"`
	TurnID    TurnID                `json:"turn_id,omitempty"`
	RunID     RunID                 `json:"run_id,omitempty"`
	Step      int                   `json:"step,omitempty"`
	Kind      ThreadDetailEventKind `json:"kind"`
	Type      string                `json:"type,omitempty"`
	CreatedAt time.Time             `json:"created_at"`

	Message    *ThreadDetailMessage    `json:"message,omitempty"`
	ToolCall   *ThreadDetailToolCall   `json:"tool_call,omitempty"`
	ToolResult *ThreadDetailToolResult `json:"tool_result,omitempty"`
	Approval   *ThreadDetailApproval   `json:"approval,omitempty"`
	TurnMarker *ThreadDetailTurnMarker `json:"turn_marker,omitempty"`
	Compaction *ThreadDetailCompaction `json:"compaction,omitempty"`
	Error      string                  `json:"error,omitempty"`
	Metadata   map[string]string       `json:"metadata,omitempty"`

	ActivityTimeline *observation.ActivityTimeline `json:"activity_timeline,omitempty"`
}

type ThreadDetailEventKind added in v0.3.42 

type ThreadDetailEventKind string
const (
	ThreadDetailEventUserMessage      ThreadDetailEventKind = "user_message"
	ThreadDetailEventAssistantMessage ThreadDetailEventKind = "assistant_message"
	ThreadDetailEventToolCall         ThreadDetailEventKind = "tool_call"
	ThreadDetailEventToolDispatch     ThreadDetailEventKind = "tool_dispatch"
	ThreadDetailEventToolActivity     ThreadDetailEventKind = "tool_activity"
	ThreadDetailEventToolResult       ThreadDetailEventKind = "tool_result"
	ThreadDetailEventTurnMarker       ThreadDetailEventKind = "turn_marker"
	ThreadDetailEventCompaction       ThreadDetailEventKind = "compaction"
	ThreadDetailEventError            ThreadDetailEventKind = "error"
	ThreadDetailEventApproval         ThreadDetailEventKind = "approval"
	ThreadDetailEventInput            ThreadDetailEventKind = "input"
	ThreadDetailEventCustom           ThreadDetailEventKind = "custom"
)

type ThreadDetailEvents added in v0.3.42 

type ThreadDetailEvents struct {
	Events       []ThreadDetailEvent `json:"events"`
	NextOrdinal  int64               `json:"next_ordinal,omitempty"`
	HasMore      bool                `json:"has_more,omitempty"`
	RetainedFrom int64               `json:"retained_from,omitempty"`
	GeneratedAt  time.Time           `json:"generated_at"`
}

type ThreadDetailMessage added in v0.3.42 

type ThreadDetailMessage struct {
	Role        string                            `json:"role,omitempty"`
	Kind        string                            `json:"kind,omitempty"`
	Preview     string                            `json:"preview,omitempty"`
	Content     string                            `json:"content,omitempty"`
	Attachments []MessageAttachment               `json:"attachments,omitempty"`
	Reasoning   string                            `json:"reasoning,omitempty"`
	Activity    *observation.ActivityPresentation `json:"activity,omitempty"`
}

type ThreadDetailToolCall added in v0.3.42 

type ThreadDetailToolCall struct {
	ID            string                     `json:"id,omitempty"`
	Name          string                     `json:"name,omitempty"`
	ArgsPreview   string                     `json:"args_preview,omitempty"`
	ArgsJSON      string                     `json:"args_json,omitempty"`
	ArgsHash      string                     `json:"args_hash,omitempty"`
	ControlSignal *ThreadDetailControlSignal `json:"control_signal,omitempty"`
}

type ThreadDetailToolResult added in v0.3.42 

type ThreadDetailToolResult struct {
	CallID        string       `json:"call_id,omitempty"`
	ToolName      string       `json:"tool_name,omitempty"`
	Status        string       `json:"status,omitempty"`
	Preview       string       `json:"preview,omitempty"`
	Content       string       `json:"content,omitempty"`
	Truncated     bool         `json:"truncated,omitempty"`
	OriginalBytes int          `json:"original_bytes,omitempty"`
	VisibleBytes  int          `json:"visible_bytes,omitempty"`
	OriginalLines int          `json:"original_lines,omitempty"`
	VisibleLines  int          `json:"visible_lines,omitempty"`
	Strategy      string       `json:"strategy,omitempty"`
	ContentSHA256 string       `json:"content_sha256,omitempty"`
	FullOutput    *ArtifactRef `json:"full_output,omitempty"`
}

type ThreadDetailTurnMarker added in v0.3.42 

type ThreadDetailTurnMarker struct {
	Status   string            `json:"status,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ThreadForkHost added in v0.15.0 

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

ThreadForkHost is the coordinator capability that forks a canonical thread.

func NewThreadForkHost added in v0.15.0 

func NewThreadForkHost(opts ThreadCapabilityOptions) (*ThreadForkHost, error)

func (*ThreadForkHost) ForkThread added in v0.15.0 

func (h *ThreadForkHost) ForkThread(ctx context.Context, req ForkThreadRequest) (ForkThreadResult, error)

type ThreadID added in v0.3.0 

type ThreadID string

type ThreadOverview added in v0.12.0 

type ThreadOverview struct {
	Thread     ThreadSnapshot      `json:"thread"`
	LatestTurn *ThreadTurnSnapshot `json:"latest_turn,omitempty"`
}

type ThreadPhase added in v0.3.0 

type ThreadPhase string
const (
	ThreadPhaseIdle ThreadPhase = "idle"
	ThreadPhaseTurn ThreadPhase = "turn"
)

type ThreadReadHost added in v0.15.0 

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

ThreadReadHost reads canonical thread and SubAgent projections without mutation.

func NewThreadReadHost added in v0.15.0 

func NewThreadReadHost(opts ThreadCapabilityOptions) (*ThreadReadHost, error)

func (*ThreadReadHost) ListSubAgentActivityTimeline added in v0.15.0 

func (h *ThreadReadHost) ListSubAgentActivityTimeline(ctx context.Context, req ListSubAgentActivityTimelineRequest) (SubAgentActivityTimelineResult, error)

func (*ThreadReadHost) ListSubAgentDetailEvents added in v0.15.0 

func (h *ThreadReadHost) ListSubAgentDetailEvents(ctx context.Context, req ListSubAgentDetailEventsRequest) (SubAgentDetailEvents, error)

func (*ThreadReadHost) ListSubAgents added in v0.15.0 

func (h *ThreadReadHost) ListSubAgents(ctx context.Context, parentThreadID ThreadID) ([]SubAgentSnapshot, error)

func (*ThreadReadHost) ListThreadDetailEvents added in v0.15.0 

func (h *ThreadReadHost) ListThreadDetailEvents(ctx context.Context, req ListThreadDetailEventsRequest) (ThreadDetailEvents, error)

func (*ThreadReadHost) ListThreadTurns added in v0.15.0 

func (h *ThreadReadHost) ListThreadTurns(ctx context.Context, req ListThreadTurnsRequest) (ThreadTurnsPage, error)

func (*ThreadReadHost) ReadLatestThreadTurn added in v0.15.0 

func (h *ThreadReadHost) ReadLatestThreadTurn(ctx context.Context, threadID ThreadID) (ThreadTurnSnapshot, error)

func (*ThreadReadHost) ReadSubAgentDetail added in v0.15.0 

func (h *ThreadReadHost) ReadSubAgentDetail(ctx context.Context, req ReadSubAgentDetailRequest) (SubAgentDetail, error)

func (*ThreadReadHost) ReadThread added in v0.15.0 

func (h *ThreadReadHost) ReadThread(ctx context.Context, threadID ThreadID) (ThreadSnapshot, error)

func (*ThreadReadHost) ReadThreadAgentTodos added in v0.15.0 

func (h *ThreadReadHost) ReadThreadAgentTodos(ctx context.Context, threadID ThreadID) (ThreadAgentTodoState, error)

func (*ThreadReadHost) ReadThreadContext added in v0.15.0 

func (h *ThreadReadHost) ReadThreadContext(ctx context.Context, threadID ThreadID) (ThreadContextSnapshot, error)

func (*ThreadReadHost) ReadThreadOverview added in v0.15.0 

func (h *ThreadReadHost) ReadThreadOverview(ctx context.Context, threadID ThreadID) (ThreadOverview, error)

func (*ThreadReadHost) ReadTurnProjection added in v0.15.0 

func (h *ThreadReadHost) ReadTurnProjection(ctx context.Context, req ReadTurnProjectionRequest) (ThreadTurnProjection, error)

type ThreadSnapshot added in v0.3.0 

type ThreadSnapshot struct {
	ID               ThreadID     `json:"id"`
	Title            string       `json:"title,omitempty"`
	TitleStatus      string       `json:"title_status,omitempty"`
	TitleSource      string       `json:"title_source,omitempty"`
	TitleUpdatedAt   time.Time    `json:"title_updated_at,omitempty"`
	TitleError       string       `json:"title_error,omitempty"`
	CreatedAt        time.Time    `json:"created_at"`
	UpdatedAt        time.Time    `json:"updated_at"`
	Phase            ThreadPhase  `json:"phase"`
	Status           ThreadStatus `json:"status"`
	LatestTurnID     TurnID       `json:"latest_turn_id,omitempty"`
	LatestRunID      RunID        `json:"latest_run_id,omitempty"`
	ThroughOrdinal   int64        `json:"through_ordinal"`
	WaitingPrompt    string       `json:"waiting_prompt,omitempty"`
	Recoverable      bool         `json:"recoverable"`
	CanAppendMessage bool         `json:"can_append_message"`
	CanRetry         bool         `json:"can_retry"`
}

type ThreadStatus added in v0.3.0 

type ThreadStatus string
const (
	ThreadStatusIdle        ThreadStatus = "idle"
	ThreadStatusRunning     ThreadStatus = "running"
	ThreadStatusCompleted   ThreadStatus = "completed"
	ThreadStatusWaiting     ThreadStatus = "waiting"
	ThreadStatusFailed      ThreadStatus = "failed"
	ThreadStatusCancelled   ThreadStatus = "cancelled"
	ThreadStatusInterrupted ThreadStatus = "interrupted"
)

type ThreadSummary added in v0.3.44 

type ThreadSummary struct {
	ID               ThreadID     `json:"id"`
	Title            string       `json:"title,omitempty"`
	TitleStatus      string       `json:"title_status,omitempty"`
	TitleSource      string       `json:"title_source,omitempty"`
	TitleUpdatedAt   time.Time    `json:"title_updated_at,omitempty"`
	TitleError       string       `json:"title_error,omitempty"`
	CreatedAt        time.Time    `json:"created_at"`
	UpdatedAt        time.Time    `json:"updated_at"`
	Phase            ThreadPhase  `json:"phase"`
	Status           ThreadStatus `json:"status"`
	LatestTurnID     TurnID       `json:"latest_turn_id,omitempty"`
	WaitingPrompt    string       `json:"waiting_prompt,omitempty"`
	Recoverable      bool         `json:"recoverable"`
	CanAppendMessage bool         `json:"can_append_message"`
	CanRetry         bool         `json:"can_retry"`
}

type ThreadTitleHost added in v0.15.0 

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

ThreadTitleHost is the coordinator capability that writes a canonical title.

func NewThreadTitleHost added in v0.15.0 

func NewThreadTitleHost(opts ThreadCapabilityOptions) (*ThreadTitleHost, error)

func (*ThreadTitleHost) SetThreadTitle added in v0.15.0 

func (h *ThreadTitleHost) SetThreadTitle(ctx context.Context, req SetThreadTitleRequest) (ThreadSnapshot, error)

type ThreadTitleMode added in v0.6.0 

type ThreadTitleMode string

ThreadTitleMode selects who owns durable thread title generation. 

const (
	ThreadTitleModeHostOwned ThreadTitleMode = "host_owned"
	ThreadTitleModeProvider  ThreadTitleMode = "provider"
)

type ThreadTurnProjection added in v0.3.49 

type ThreadTurnProjection struct {
	ThreadID       ThreadID                      `json:"thread_id"`
	TurnID         TurnID                        `json:"turn_id"`
	RunID          RunID                         `json:"run_id"`
	TraceID        TraceID                       `json:"trace_id,omitempty"`
	Status         TurnStatus                    `json:"status"`
	Segments       []ThreadTurnProjectionSegment `json:"segments,omitempty"`
	ThroughOrdinal int64                         `json:"through_ordinal"`
	ProjectedAt    time.Time                     `json:"projected_at,omitempty"`
}

func ProjectThreadTurn added in v0.3.49 

func ProjectThreadTurn(req ProjectThreadTurnRequest) ThreadTurnProjection

func (ThreadTurnProjection) Validate added in v0.7.0 

func (p ThreadTurnProjection) Validate() error

type ThreadTurnProjectionSegment added in v0.3.49 

type ThreadTurnProjectionSegment struct {
	Kind             ThreadTurnProjectionSegmentKind `json:"kind"`
	Text             string                          `json:"text,omitempty"`
	ActivityTimeline *observation.ActivityTimeline   `json:"activity_timeline,omitempty"`
	Signal           *ThreadTurnProjectionSignal     `json:"signal,omitempty"`
	EventIDs         []string                        `json:"event_ids,omitempty"`
}

type ThreadTurnProjectionSegmentKind added in v0.3.49 

type ThreadTurnProjectionSegmentKind string
const (
	ThreadTurnProjectionSegmentAssistantText    ThreadTurnProjectionSegmentKind = "assistant_text"
	ThreadTurnProjectionSegmentActivityTimeline ThreadTurnProjectionSegmentKind = "activity_timeline"
	ThreadTurnProjectionSegmentControlSignal    ThreadTurnProjectionSegmentKind = "control_signal"
)

type ThreadTurnProjectionSignal added in v0.3.49 

type ThreadTurnProjectionSignal struct {
	Name        string         `json:"name,omitempty"`
	CallID      string         `json:"call_id,omitempty"`
	Disposition string         `json:"disposition,omitempty"`
	Text        string         `json:"text,omitempty"`
	ArgsHash    string         `json:"args_hash,omitempty"`
	Payload     map[string]any `json:"payload,omitempty"`
}

type ThreadTurnSnapshot added in v0.11.0 

type ThreadTurnSnapshot struct {
	TurnID          TurnID                `json:"turn_id"`
	RunID           RunID                 `json:"run_id"`
	Ordinal         int64                 `json:"ordinal"`
	StartedAt       time.Time             `json:"started_at"`
	UpdatedAt       time.Time             `json:"updated_at"`
	UserEntryID     string                `json:"user_entry_id,omitempty"`
	UserInput       string                `json:"user_input,omitempty"`
	UserAttachments []MessageAttachment   `json:"user_attachments,omitempty"`
	Status          TurnStatus            `json:"status"`
	Failure         string                `json:"failure,omitempty"`
	Projection      ThreadTurnProjection  `json:"projection"`
	ControlSignals  []ThreadControlSignal `json:"control_signals,omitempty"`
	ThroughOrdinal  int64                 `json:"through_ordinal"`
}

type ThreadTurnsPage added in v0.11.0 

type ThreadTurnsPage struct {
	ThreadID       ThreadID             `json:"thread_id"`
	Turns          []ThreadTurnSnapshot `json:"turns"`
	HasMore        bool                 `json:"has_more,omitempty"`
	ThroughOrdinal int64                `json:"through_ordinal"`
	GeneratedAt    time.Time            `json:"generated_at"`
}

type ToolSurface added in v0.3.40 

type ToolSurface struct {
	Tools                 *tools.Registry
	ToolDefinitions       []tools.ToolDefinition
	HostedToolDefinitions []HostedToolDefinition
	SystemPrompt          string
	HostContext           map[string]string
	Epoch                 string
	Reason                string
}

ToolSurface is the host-supplied tool view for the current run phase. It is product-neutral: hosts own policy names and may project them into tools, prompt text, or host context without Floret interpreting them.

type ToolSurfaceProvider added in v0.3.40 

type ToolSurfaceProvider func(context.Context, ToolSurfaceRequest) (ToolSurface, error)

type ToolSurfaceRequest added in v0.3.40 

type ToolSurfaceRequest struct {
	RunID         RunID
	ThreadID      ThreadID
	TurnID        TurnID
	TraceID       TraceID
	PromptScopeID PromptScopeID
	Step          int
	Phase         string
	Labels        RunLabels
	HostContext   map[string]string
}

ToolSurfaceRequest identifies the run phase asking for the current host tool surface. Hosts may use it to refresh tool visibility, hosted tools, prompt instructions, and host context between provider requests and tool dispatch.

type TraceID added in v0.3.0 

type TraceID string

type TurnCompletionPolicy added in v0.3.1 

type TurnCompletionPolicy string

TurnCompletionPolicy controls how the provider loop may finish. The zero value uses natural stops. 

const (
	// TurnCompletionNaturalStop lets the provider's natural stop finish the run.
	TurnCompletionNaturalStop TurnCompletionPolicy = "natural_stop"
	// TurnCompletionExplicitSignal requires a projected turn signal to finish or
	// pause the run.
	TurnCompletionExplicitSignal TurnCompletionPolicy = "explicit_signal"
)

type TurnID added in v0.3.0 

type TurnID string

type TurnInput added in v0.12.0 

type TurnInput struct {
	Text        string              `json:"text,omitempty"`
	Attachments []MessageAttachment `json:"attachments,omitempty"`
}

func (TurnInput) Validate added in v0.12.0 

func (i TurnInput) Validate() error

type TurnLimits added in v0.3.1 

type TurnLimits struct {
	MaxInputTokens           int64
	MaxTotalTokens           int64
	MaxCostUSD               float64
	MaxToolCalls             int
	MaxLengthContinuations   int
	MaxStopHookContinuations int
}

TurnLimits contains per-run budget and continuation caps.

type TurnProjectionAvailability added in v0.7.0 

type TurnProjectionAvailability string
const (
	TurnProjectionAvailabilityReady       TurnProjectionAvailability = "ready"
	TurnProjectionAvailabilityUnavailable TurnProjectionAvailability = "unavailable"
)

func (TurnProjectionAvailability) Valid added in v0.7.0 

func (a TurnProjectionAvailability) Valid() bool

type TurnResult added in v0.3.0 

type TurnResult struct {
	ThreadID               ThreadID                       `json:"thread_id"`
	TurnID                 TurnID                         `json:"turn_id"`
	RunID                  RunID                          `json:"run_id"`
	Status                 TurnStatus                     `json:"status"`
	Output                 string                         `json:"output,omitempty"`
	Error                  string                         `json:"error,omitempty"`
	Diagnostics            map[string]string              `json:"diagnostics,omitempty"`
	Metrics                RunMetrics                     `json:"metrics"`
	CompletionReason       observation.CompletionReason   `json:"completion_reason,omitempty"`
	ContinuationReason     observation.ContinuationReason `json:"continuation_reason,omitempty"`
	FinishReason           observation.FinishReason       `json:"finish_reason,omitempty"`
	RawFinishReason        string                         `json:"raw_finish_reason,omitempty"`
	FinishInferred         bool                           `json:"finish_inferred,omitempty"`
	Signal                 *TurnSignal                    `json:"signal,omitempty"`
	ActivityTimeline       observation.ActivityTimeline   `json:"activity_timeline"`
	ProjectionAvailability TurnProjectionAvailability     `json:"projection_availability"`
	Projection             *ThreadTurnProjection          `json:"projection,omitempty"`
	ProjectionError        string                         `json:"projection_error,omitempty"`
	PendingApprovals       []PendingApproval              `json:"pending_approvals,omitempty"`
}

func (TurnResult) Validate added in v0.10.0 

func (r TurnResult) Validate() error

type TurnSignal added in v0.3.1 

type TurnSignal struct {
	Disposition SignalDisposition                 `json:"disposition"`
	Name        string                            `json:"name"`
	CallID      string                            `json:"call_id,omitempty"`
	Payload     map[string]any                    `json:"payload,omitempty"`
	Activity    *observation.ActivityPresentation `json:"activity,omitempty"`
	OutputText  string                            `json:"output_text,omitempty"`
	ArgsHash    string                            `json:"args_hash,omitempty"`
	Labels      map[string]string                 `json:"labels,omitempty"`
}

TurnSignal is a host-safe projection of a signal tool call.

func ProjectCoreControlSignal added in v0.3.10 

func ProjectCoreControlSignal(call tools.ToolCall) (TurnSignal, bool, error)

ProjectCoreControlSignal projects ask_user/task_complete tool calls into Floret control signals. Host-specific modes and UI payloads stay outside this helper.

type TurnSignalSpec added in v0.3.1 

type TurnSignalSpec struct {
	Definitions []tools.ToolDefinition
	Project     func(tools.ToolCall) (TurnSignal, bool, error)
}

TurnSignalSpec lets a host declare provider-visible signal tools without importing Floret implementation packages.

type TurnStatus added in v0.3.0 

type TurnStatus string
const (
	TurnStatusRunning   TurnStatus = "running"
	TurnStatusCompleted TurnStatus = "completed"
	TurnStatusWaiting   TurnStatus = "waiting"
	TurnStatusFailed    TurnStatus = "failed"
	TurnStatusCancelled TurnStatus = "cancelled"
)

func (TurnStatus) IsTerminal added in v0.7.0 

func (s TurnStatus) IsTerminal() bool

func (TurnStatus) Valid added in v0.7.0 

func (s TurnStatus) Valid() bool

type TurnSupplementalContextItem added in v0.3.89 

type TurnSupplementalContextItem struct {
	Kind      string
	Title     string
	Text      string
	Metadata  map[string]string
	Sensitive bool
	Truncated bool
}

TurnSupplementalContextItem is host-provided context that is visible only to the current model turn. It does not change the user's input text, durable thread history, working directory, permissions, or provider continuation state.

type UpdateThreadAgentTodosRequest added in v0.11.0 

type UpdateThreadAgentTodosRequest struct {
	ThreadID        ThreadID
	ExpectedVersion int64
	Items           []AgentTodo
	TurnID          TurnID
	RunID           RunID
	ToolCallID      string
}

type WaitSubAgentsRequest added in v0.3.17 

type WaitSubAgentsRequest struct {
	ParentThreadID ThreadID
	ChildThreadIDs []ThreadID
	Timeout        time.Duration
}

type WaitSubAgentsResult added in v0.3.17 

type WaitSubAgentsResult struct {
	Snapshots []SubAgentSnapshot `json:"snapshots"`
	TimedOut  bool               `json:"timed_out,omitempty"`
}

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.