runtime

package
v7.1.2 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package runtime exposes Floret's durable, host-facing Agent runtime.

Floret owns canonical threads, turns, runs, provider-visible history, approvals, Agent todos, tool outcomes, projections, and recovery state. A host retains product policy, authorization, resources, model transport, UI, and commands that have not yet been admitted to a Floret thread.

Hosts create one store, configure its capability binders exactly once with configureHostCapabilities, bind the narrow capability needed for an exact ThreadID or parent ThreadID, and close the store only after active work has stopped. Public snapshot and result Validate methods are intended for host integration boundaries; invalid values must not be repaired from host metadata, observation events, or Floret implementation records.

Bind methods bind an identity or intent without first claiming that the referenced store state exists. Provider-free capabilities that require existing authority use NewHost(ctx, ...) so construction can validate the store. Recovery keeps explicit BindThread and BindSubAgent entry points because root and parent-child recovery authority are different contracts. Provider-backed factories accept only opaque option values returned by newTurnExecutionOptions, newThreadCompactionOptions, or newSubAgentOptions; factories revalidate both those values and current store authority before issuing a Host.

Index

Constants

View Source 
const (
	MessageReferenceText      MessageReferenceKind = "text"
	MessageReferenceFile      MessageReferenceKind = "file"
	MessageReferenceDirectory MessageReferenceKind = "directory"
	MessageReferenceTerminal  MessageReferenceKind = "terminal"
	MessageReferenceProcess   MessageReferenceKind = "process"

	MaxMessageReferencesPerTurn           = 128
	MaxMessageReferenceIDBytes            = 128
	MaxMessageReferenceLabelRunes         = 256
	MaxMessageReferenceTextRunes          = 12_000
	MaxMessageReferenceResourceRefBytes   = 8_192
	MaxMessageReferencesPayloadBytes      = 256 * 1024
	MaxMessageAttachmentsPerTurn          = 32
	MaxMessageAttachmentResourceRefBytes  = 16 * 1024
	MaxMessageAttachmentNameRunes         = 1024
	MaxMessageAttachmentMIMETypeBytes     = 512
	MaxMessageAttachmentSizeBytes         = 64 * 1024 * 1024
	MaxMessageAttachmentsTotalSizeBytes   = 256 * 1024 * 1024
	MaxMessageAttachmentsPayloadBytes     = 512 * 1024
	MaxTurnSupplementalContextItems       = 128
	MaxTurnSupplementalContextKindRunes   = 128
	MaxTurnSupplementalContextTitleRunes  = 256
	MaxTurnSupplementalContextTextRunes   = 16_384
	MaxTurnSupplementalMetadataPairs      = 32
	MaxTurnSupplementalMetadataKeyBytes   = 128
	MaxTurnSupplementalMetadataValueRunes = 4_096
	MaxTurnSupplementalPayloadBytes       = 256 * 1024
)
View Source 
const (
	CoreControlAskUser = tools.ControlAskUser
)

Variables

View Source 
var (
	// ErrMigrationRequired reports an exact legacy schema that runtime.Open
	// refuses to migrate implicitly.
	ErrMigrationRequired = errors.New("floret storage migration required")
	// ErrUnsupportedSchema reports a nonempty schema outside the v3 contract.
	ErrUnsupportedSchema = errors.New("unsupported floret logical schema")
)
View Source 
var (
	// ErrHostClosed reports that Host shutdown has started.
	ErrHostClosed = errors.New("floret host is closed")
	// ErrRevisionUnavailable reports a thread revision outside retained durable history.
	ErrRevisionUnavailable = errors.New("floret thread revision is unavailable")
	// ErrSubscriptionStale reports a subscription that must be recreated from a new snapshot.
	ErrSubscriptionStale = errors.New("floret subscription is stale")
	// ErrThreadNotFound reports that a requested durable thread was not found.
	ErrThreadNotFound = errors.New("floret thread not found")
	// ErrThreadDeleted reports that a requested durable identity is permanently tombstoned.
	ErrThreadDeleted = errors.New("floret thread is deleted")
	// ErrThreadNotActive reports that an active-only capability no longer owns the thread mutation.
	ErrThreadNotActive = errors.New("floret thread is not active")
	// ErrThreadBusy reports that another active turn or mutation currently owns the thread.
	ErrThreadBusy = errors.New("floret thread is busy")
	// ErrTurnNotFound reports that a requested durable turn was not found.
	ErrTurnNotFound = errors.New("floret turn not found")
	// ErrInterruptedTurnNotFound reports that a live exact recovery target has no active turn lease.
	ErrInterruptedTurnNotFound = errors.New("floret interrupted turn not found")
	// ErrRecoveryTargetResolved reports that an exact interrupted-turn target no longer owns its bound lease generation.
	ErrRecoveryTargetResolved = errors.New("floret interrupted turn recovery target is resolved")
	// ErrRunNotFound reports that a requested durable run was not found.
	ErrRunNotFound = errors.New("floret run not found")
	// ErrArtifactNotFound reports that a requested durable artifact was not found.
	ErrArtifactNotFound = errors.New("floret artifact not found")
	// ErrNoRetryTarget reports that a thread has no canonical turn eligible for retry.
	ErrNoRetryTarget = errors.New("floret thread has no retry target")
	// ErrPendingToolNotFound reports that a settlement target does not identify a canonical tool call.
	ErrPendingToolNotFound = errors.New("floret pending tool not found")
	// ErrPendingToolNotActive reports that a settlement target is not an active pending tool result.
	ErrPendingToolNotActive = errors.New("floret pending tool is not active")
	// ErrPendingToolSettlementConflict reports that a pending tool was already settled differently.
	ErrPendingToolSettlementConflict = errors.New("floret pending tool settlement conflict")
	// ErrSubAgentNotFound reports that a requested parent-scoped child thread was not found.
	ErrSubAgentNotFound = errors.New("floret subagent not found")
	// ErrSubAgentClosed reports that a requested child mutation targets a closed SubAgent.
	ErrSubAgentClosed = errors.New("floret subagent is closed")
	// ErrSubAgentClosing reports that an explicit close operation owns the child subtree.
	ErrSubAgentClosing = errors.New("floret subagent is closing")
	// ErrStaleAuthority reports that a local proof no longer owns the durable generation.
	ErrStaleAuthority = errors.New("floret authority proof is stale")
	// ErrRequestConflict reports durable request identity reuse with changed input.
	ErrRequestConflict = errors.New("floret request conflicts with persisted authority")
	// ErrAuthorityCorrupt reports an impossible durable authority shape.
	ErrAuthorityCorrupt = errors.New("floret authority state is corrupt")
	// ErrUnsupportedStoreCapability reports a backend that lacks required atomicity.
	ErrUnsupportedStoreCapability = errors.New("floret store capability is unsupported")
	// ErrEffectUnauthorized reports a current host-policy denial before handler entry.
	ErrEffectUnauthorized = errors.New("floret effect is unauthorized")
	// ErrAuthorizationUnavailable reports a host-policy, approval, audit, or gate failure before handler entry.
	ErrAuthorizationUnavailable = errors.New("floret effect authorization is unavailable")
	// ErrInvalidAuthorizationProof reports a proof that does not match the canonical invocation.
	ErrInvalidAuthorizationProof = errors.New("floret effect authorization proof is invalid")
	// ErrEffectDispatchConsumed reports reuse or deferred use of a one-shot authorized effect.
	ErrEffectDispatchConsumed = errors.New("floret authorized effect dispatch was consumed")
	// ErrEffectOutcomeUnknown reports an invocation that crossed dispatch without a known result.
	ErrEffectOutcomeUnknown = errors.New("floret effect outcome is unknown")
	// ErrAuthorizationContract reports a host gate that did not return the closure's sealed result.
	ErrAuthorizationContract = errors.New("floret effect authorization contract failed")
	// ErrStoreClosed reports that the store has started closing.
	ErrStoreClosed = ErrHostClosed
	// ErrSubAgentParentRequired reports that a child operation used a root-thread capability.
	ErrSubAgentParentRequired = errors.New("floret subagent operation requires parent authority")
	// 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")
	// 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")
	// ErrThreadAuthorityInvariant reports invalid durable root/SubAgent ownership metadata.
	ErrThreadAuthorityInvariant = errors.New("floret thread authority invariant violated")
)
View Source 
var (
	// ErrStorageResetUnsupported reports a backend that cannot atomically clear
	// all Floret-owned opaque records.
	ErrStorageResetUnsupported = errors.New("Floret storage reset is unsupported")
	// ErrStorageResetRequest reports incomplete reset ownership metadata.
	ErrStorageResetRequest = errors.New("invalid Floret storage reset request")
)

Functions

func CoreControlDefinitions 

func CoreControlDefinitions() []tools.ToolDefinition

CoreControlDefinitions returns Floret's product-neutral ask-user control tool.

func ManualCompactionOperationID 

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

func ProviderSafeCoreControlText 

func ProviderSafeCoreControlText(signal TurnSignal) string

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

Types

type Agent 

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

Agent is an immutable assistant persona and execution-capability snapshot. It contains no durable conversation identity or storage ownership.

func NewAgent 

func NewAgent(configuration config.AgentConfig, gateway provider.Gateway, options ...AgentOption) (*Agent, error)

NewAgent validates and snapshots one provider-neutral Agent configuration.

func (*Agent) Config 

func (agent *Agent) Config() config.AgentConfig

Config returns a detached copy of the Agent's persona and model policy.

func (*Agent) ProviderIdentity 

func (agent *Agent) ProviderIdentity() provider.Identity

ProviderIdentity returns the immutable identity declared by the Gateway.

func (*Agent) ToolDefinitions 

func (agent *Agent) ToolDefinitions() []tools.ToolDefinition

ToolDefinitions returns detached provider-visible definitions for the Agent's static tool snapshot.

type AgentFactory 

type AgentFactory interface {
	Agent(context.Context, AgentRequest) (*Agent, error)
}

AgentFactory resolves provider and tool capability outside the thread lock.

type AgentFactoryFunc 

type AgentFactoryFunc func(context.Context, AgentRequest) (*Agent, error)

AgentFactoryFunc adapts a function to AgentFactory.

func (AgentFactoryFunc) Agent 

func (factory AgentFactoryFunc) Agent(ctx context.Context, request AgentRequest) (*Agent, error)

type AgentOption 

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

AgentOption configures one immutable Agent capability at construction time.

func WithAgentCapabilities 

func WithAgentCapabilities(capabilities CapabilityOptions) AgentOption

WithAgentCapabilities configures product-neutral capability sources.

func WithAgentDynamicToolSurface 

func WithAgentDynamicToolSurface(surface ToolSurfaceProvider) AgentOption

WithAgentDynamicToolSurface configures the product-neutral per-step tool surface source.

func WithAgentEffectAuthorization 

func WithAgentEffectAuthorization(gate EffectAuthorizationGate) AgentOption

WithAgentEffectAuthorization configures the host-owned authorization gate for effectful local tools.

func WithAgentEventSink 

func WithAgentEventSink(sink EventSink) AgentOption

WithAgentEventSink configures runtime event observation.

func WithAgentIDGenerator 

func WithAgentIDGenerator(generator func(string) string) AgentOption

WithAgentIDGenerator configures deterministic non-domain correlation IDs.

func WithAgentLoopLimits 

func WithAgentLoopLimits(limits LoopLimits) AgentOption

WithAgentLoopLimits configures provider-loop safety limits.

func WithAgentManualCompactions 

func WithAgentManualCompactions(source ManualCompactionSource) AgentOption

WithAgentManualCompactions configures host-owned manual compaction requests that are polled at safe points during each turn executed by the Agent.

func WithAgentRunLabels added in v7.1.0 

func WithAgentRunLabels(labels RunLabels) AgentOption

WithAgentRunLabels snapshots provider-neutral correlation labels and opaque host execution context for every run executed by the Agent.

func WithAgentSubAgentTimeout 

func WithAgentSubAgentTimeout(timeout time.Duration) AgentOption

WithAgentSubAgentTimeout bounds one child execution.

func WithAgentThreadTitleMode 

func WithAgentThreadTitleMode(mode ThreadTitleMode) AgentOption

WithAgentThreadTitleMode configures host-owned or provider-owned titles.

func WithAgentTools 

func WithAgentTools(items ...tools.Tool) AgentOption

WithAgentTools snapshots static local tools for every execution by the Agent.

type AgentRequest 

type AgentRequest struct {
	ThreadID           identity.ThreadID
	TurnID             identity.TurnID
	RequestKey         string
	Input              UserInput
	CanonicalTurnInput UserInput
	RetrySource        identity.TurnID
	InteractionID      string
	EffectAttemptID    string
}

AgentRequest identifies one typed execution whose provider and tool surface must be resolved outside the thread lock. Run identities remain internal.

type ApprovalPresentation 

type ApprovalPresentation struct {
	Label       string   `json:"label"`
	Description string   `json:"description,omitempty"`
	Command     string   `json:"command,omitempty"`
	Effects     []string `json:"effects,omitempty"`
	Targets     []string `json:"targets,omitempty"`
	Risk        string   `json:"risk,omitempty"`
	ToolName    string   `json:"tool_name"`
	ToolCallID  string   `json:"tool_call_id"`
}

type AttentionSummary 

type AttentionSummary struct {
	ApprovalCount int `json:"approval_count"`
	InputCount    int `json:"input_count"`
}

type AuthorityBusyError 

type AuthorityBusyError struct {
	Kind AuthorityBusyKind
	Err  error
}

AuthorityBusyError classifies which durable authority family blocked an operation without exposing an owner identity.

func (*AuthorityBusyError) Error 

func (e *AuthorityBusyError) Error() string

func (*AuthorityBusyError) Is 

func (e *AuthorityBusyError) Is(target error) bool

func (*AuthorityBusyError) Unwrap 

func (e *AuthorityBusyError) Unwrap() error

type AuthorityBusyKind 

type AuthorityBusyKind string
const (
	AuthorityBusyTurn      AuthorityBusyKind = "turn"
	AuthorityBusyAuthority AuthorityBusyKind = "authority"
)

type AuthorizedEffect 

type AuthorizedEffect func(context.Context, EffectAuthorizationProof) (EffectDispatchResult, error)

AuthorizedEffect invokes one prepared effect under the host-selected execution context. Floret additionally bounds that context by the active turn.

type CancelInput 

type CancelInput struct {
	ThreadID   identity.ThreadID `json:"thread_id"`
	RequestKey RequestKey        `json:"request_key"`
}

type CapabilityOptions 

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

type CommittedCleanupError 

type CommittedCleanupError struct {
	ThreadID identity.ThreadID
	Err      error
}

CommittedCleanupError reports that canonical deletion committed and only physical or auxiliary cleanup remains retryable.

func (*CommittedCleanupError) Error 

func (e *CommittedCleanupError) Error() string

func (*CommittedCleanupError) Unwrap 

func (e *CommittedCleanupError) Unwrap() error

type CommittedEffectError 

type CommittedEffectError struct {
	EffectAttemptID string
	Err             error
}

func (*CommittedEffectError) Error 

func (e *CommittedEffectError) Error() string

func (*CommittedEffectError) Unwrap 

func (e *CommittedEffectError) Unwrap() error

type ContractError 

type ContractError struct {
	Contract string
	Err      error
}

ContractError identifies a corrupt public result contract. Contract names the root DTO or projection without exposing internal store records.

func (*ContractError) Error 

func (e *ContractError) Error() string

func (*ContractError) Is 

func (e *ContractError) Is(target error) bool

func (*ContractError) Unwrap 

func (e *ContractError) Unwrap() error

type CreateThreadInput 

type CreateThreadInput struct {
	ParentThreadID  identity.ThreadID `json:"parent_thread_id,omitempty"`
	ParentTurnID    identity.TurnID   `json:"parent_turn_id,omitempty"`
	TaskName        string            `json:"task_name,omitempty"`
	TaskDescription string            `json:"task_description,omitempty"`
	HostProfileRef  string            `json:"host_profile_ref,omitempty"`
	ForkMode        string            `json:"fork_mode,omitempty"`
	RequestKey      RequestKey        `json:"request_key"`
}

type DeleteQueuedInput 

type DeleteQueuedInput struct {
	ThreadID    identity.ThreadID `json:"thread_id"`
	QueueItemID string            `json:"queue_item_id"`
	RequestKey  RequestKey        `json:"request_key"`
}

type DeleteThreadInput 

type DeleteThreadInput struct {
	ThreadID   identity.ThreadID `json:"thread_id"`
	RequestKey RequestKey        `json:"request_key"`
}

type EffectAuthorizationGate 

type EffectAuthorizationGate interface {
	Dispatch(context.Context, EffectAuthorizationRequest, AuthorizedEffect) (EffectDispatchResult, error)
}

type EffectAuthorizationGateFunc 

type EffectAuthorizationGateFunc func(context.Context, EffectAuthorizationRequest, AuthorizedEffect) (EffectDispatchResult, error)

func (EffectAuthorizationGateFunc) Dispatch 

func (f EffectAuthorizationGateFunc) Dispatch(ctx context.Context, req EffectAuthorizationRequest, effect AuthorizedEffect) (EffectDispatchResult, error)

type EffectAuthorizationProof 

type EffectAuthorizationProof struct {
	EffectAttemptID    string            `json:"effect_attempt_id"`
	RequestFingerprint string            `json:"request_fingerprint"`
	ThreadID           identity.ThreadID `json:"thread_id"`
	TurnID             identity.TurnID   `json:"turn_id"`
	RunID              identity.RunID    `json:"run_id"`
	ToolCallID         string            `json:"tool_call_id"`
	PolicyRevision     string            `json:"policy_revision"`
	ApprovalID         string            `json:"approval_id,omitempty"`
	AuditReference     string            `json:"audit_reference"`
	AuditHash          string            `json:"audit_hash"`
	AuthorizedAt       time.Time         `json:"authorized_at"`
}

type EffectAuthorizationRequest 

type EffectAuthorizationRequest struct {
	EffectAttemptID    string            `json:"effect_attempt_id"`
	RequestFingerprint string            `json:"request_fingerprint"`
	ThreadID           identity.ThreadID `json:"thread_id"`
	TurnID             identity.TurnID   `json:"turn_id"`
	RunID              identity.RunID    `json:"run_id"`
	ToolCallID         string            `json:"tool_call_id"`
	ToolName           string            `json:"tool_name"`
	Arguments          string            `json:"arguments,omitempty"`
	ArgumentHash       string            `json:"argument_hash"`
	Step               int               `json:"step"`
	BatchIndex         int               `json:"batch_index"`
	BatchSize          int               `json:"batch_size"`
	Labels             map[string]string `json:"labels,omitempty"`
	HostContext        map[string]string `json:"host_context,omitempty"`
	// Activity is detached tool-authored display data. It is never authority.
	Activity    *tools.ActivityPresentation `json:"activity,omitempty"`
	Resources   []tools.ResourceRef         `json:"resources,omitempty"`
	Effects     []tools.Effect              `json:"effects,omitempty"`
	Permission  tools.PermissionSpec        `json:"permission"`
	ReadOnly    bool                        `json:"read_only"`
	Destructive bool                        `json:"destructive"`
	OpenWorld   bool                        `json:"open_world"`
}

type EffectDispatchResult 

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

type Event 

type Event struct {
	Type               observation.EventType          `json:"type"`
	TraceID            identity.TraceID               `json:"trace_id,omitempty"`
	RunID              identity.RunID                 `json:"run_id,omitempty"`
	ThreadID           identity.ThreadID              `json:"thread_id,omitempty"`
	TurnID             identity.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           *tools.ActivityPresentation    `json:"activity,omitempty"`
	ActivityTimeline   *observation.ActivityTimeline  `json:"activity_timeline,omitempty"`
	Stream             *StreamObservation             `json:"stream,omitempty"`
	ContextStatus      *observation.ContextStatus     `json:"context_status,omitempty"`
	// ThreadUsageTotals contains cumulative canonical usage after this final
	// provider-usage record has been committed to the thread journal.
	ThreadUsageTotals *ThreadTokenUsageTotals           `json:"thread_usage_totals,omitempty"`
	Compaction        *observation.CompactionEvent      `json:"compaction,omitempty"`
	CompactionDebug   *observation.CompactionDebugEvent `json:"compaction_debug,omitempty"`
	Sources           []publicprovider.Source           `json:"sources,omitempty"`
	Metadata          map[string]any                    `json:"metadata,omitempty"`
	Timestamp         time.Time                         `json:"timestamp,omitempty"`
	// contains filtered or unexported fields
}

func (Event) Validate 

func (e Event) Validate() error

type EventSink 

type EventSink interface {
	EmitEvent(Event)
}

type ForkThreadInput 

type ForkThreadInput struct {
	SourceThreadID  identity.ThreadID `json:"source_thread_id"`
	SourceEntryID   string            `json:"source_entry_id,omitempty"`
	ParentThreadID  identity.ThreadID `json:"parent_thread_id,omitempty"`
	ParentTurnID    identity.TurnID   `json:"parent_turn_id,omitempty"`
	TaskName        string            `json:"task_name,omitempty"`
	TaskDescription string            `json:"task_description,omitempty"`
	HostProfileRef  string            `json:"host_profile_ref,omitempty"`
	ForkMode        string            `json:"fork_mode,omitempty"`
	RequestKey      RequestKey        `json:"request_key"`
}

type HistoryPage 

type HistoryPage struct {
	Items   []ThreadItem `json:"items"`
	Before  string       `json:"before,omitempty"`
	HasMore bool         `json:"has_more,omitempty"`
}

type Host 

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

Host is the composition-root owner of Floret storage and narrow capability issuance. Application services must retain only handles issued by Host.

func Open 

func Open(ctx context.Context, options Options) (*Host, error)

Open validates the exact v3 logical schema, initializes an empty Backend, and transfers exclusive backend lifecycle ownership to a new Host.

func (*Host) Shutdown 

func (host *Host) Shutdown(ctx context.Context) error

Shutdown stops in-memory executions and closes the owned canonical store.

func (*Host) ThreadService 

func (host *Host) ThreadService(factory AgentFactory) (ThreadService, error)

ThreadRuntime returns the Host-owned typed runtime service.

type IDSource 

type IDSource interface {
	NewThreadID() (identity.ThreadID, error)
	NewTurnID() (identity.TurnID, error)
	NewRunID() (identity.RunID, error)
}

IDSource supplies deterministic identities to tests. Production uses the cryptographic source installed by Open.

type ImportPendingInputsInput 

type ImportPendingInputsInput struct {
	ThreadID identity.ThreadID      `json:"thread_id"`
	Items    []ImportedPendingInput `json:"items"`
}

type ImportResult 

type ImportResult struct {
	ThreadID identity.ThreadID `json:"thread_id"`
	Imported int               `json:"imported"`
	View     ThreadView        `json:"view"`
}

type ImportedPendingInput 

type ImportedPendingInput struct {
	RequestKey          RequestKey                    `json:"request_key"`
	Input               UserInput                     `json:"input"`
	SupplementalContext []TurnSupplementalContextItem `json:"supplemental_context,omitempty"`
}

type InputPresentation 

type InputPresentation struct {
	Summary   string          `json:"summary"`
	Questions []InputQuestion `json:"questions"`
}

type InputQuestion 

type InputQuestion struct {
	ID         string   `json:"id"`
	Prompt     string   `json:"prompt"`
	Kind       string   `json:"kind"`
	Options    []string `json:"options,omitempty"`
	WriteLabel string   `json:"write_label,omitempty"`
	Secret     bool     `json:"secret,omitempty"`
}

type InteractionAnswer 

type InteractionAnswer struct {
	InteractionID string            `json:"interaction_id,omitempty"`
	Approved      *bool             `json:"approved,omitempty"`
	Input         map[string]string `json:"input,omitempty"`
}

InteractionAnswer resolves one user or approval interaction.

type InteractionResolution 

type InteractionResolution struct {
	Accepted bool              `json:"accepted"`
	Redacted bool              `json:"redacted,omitempty"`
	Outcome  string            `json:"outcome,omitempty"`
	Approved *bool             `json:"approved,omitempty"`
	Input    map[string]string `json:"input,omitempty"`
	At       time.Time         `json:"at"`
}

type LoopLimits 

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

type ManualCompactionPollRequest 

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

type ManualCompactionRequest 

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

type ManualCompactionSource 

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

type MessageAttachment 

type MessageAttachment struct {
	ResourceRef string                      `json:"resource_ref"`
	Name        string                      `json:"name"`
	MIMEType    string                      `json:"mime_type"`
	SizeBytes   int64                       `json:"size_bytes,omitempty"`
	TextStats   *MessageAttachmentTextStats `json:"text_stats,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 

func (a MessageAttachment) Validate() error

type MessageAttachmentTextStats 

type MessageAttachmentTextStats struct {
	UnicodeCodePointCount int64 `json:"unicode_code_points"`
	LogicalLineCount      int64 `json:"logical_lines"`
}

type MessageReference 

type MessageReference struct {
	ReferenceID string               `json:"reference_id"`
	Kind        MessageReferenceKind `json:"kind"`
	Label       string               `json:"label"`
	Text        string               `json:"text,omitempty"`
	ResourceRef string               `json:"resource_ref,omitempty"`
	Truncated   bool                 `json:"truncated,omitempty"`
}

MessageReference is one ordered, durable, user-visible reference associated with a canonical user message. ResourceRef is opaque to Floret.

func (MessageReference) Validate 

func (r MessageReference) Validate() error

type MessageReferenceKind 

type MessageReferenceKind string

type MigrationRequiredError 

type MigrationRequiredError struct {
	Version string
}

MigrationRequiredError identifies the exact legacy logical schema observed by runtime.Open.

func (*MigrationRequiredError) Error 

func (failure *MigrationRequiredError) Error() string

Error describes the required explicit migration.

func (*MigrationRequiredError) Is 

func (failure *MigrationRequiredError) Is(target error) bool

Is classifies MigrationRequiredError with ErrMigrationRequired.

type Options 

type Options struct {
	Storage publicstorage.Source
	// StartupProgress observes product-neutral storage startup phases. The
	// callback runs synchronously and must return promptly.
	StartupProgress StartupProgress
	// IDSource exists only for v3 source compatibility.
	// Deprecated: production hosts must leave this nil; tests should use
	// florettest.NewIDSource.
	IDSource IDSource
}

Options configures one runtime Host.

type PromoteQueuedInput 

type PromoteQueuedInput = DeleteQueuedInput

type QueuedInput 

type QueuedInput struct {
	ID                  string                        `json:"id"`
	RequestKey          string                        `json:"request_key"`
	Input               UserInput                     `json:"input"`
	SupplementalContext []TurnSupplementalContextItem `json:"supplemental_context,omitempty"`
	CreatedAt           time.Time                     `json:"created_at"`
}

QueuedInput is one accepted input waiting behind the active turn.

type ReorderQueueInput 

type ReorderQueueInput struct {
	ThreadID       identity.ThreadID `json:"thread_id"`
	OrderedItemIDs []string          `json:"ordered_item_ids"`
	RequestKey     RequestKey        `json:"request_key"`
}

type RequestConflictError 

type RequestConflictError struct {
	Operation string
	RequestID string
	Err       error
}

RequestConflictError identifies the immutable request key that was reused with different input. It never exposes the stored request payload.

func (*RequestConflictError) Error 

func (e *RequestConflictError) Error() string

func (*RequestConflictError) Is 

func (e *RequestConflictError) Is(target error) bool

func (*RequestConflictError) Unwrap 

func (e *RequestConflictError) Unwrap() error

type RequestKey 

type RequestKey string

RequestKey is the stable idempotency identity of one transport mutation.

type RespondInput 

type RespondInput struct {
	ThreadID      identity.ThreadID   `json:"thread_id"`
	InteractionID string              `json:"interaction_id"`
	Answers       []InteractionAnswer `json:"answers"`
	RequestKey    RequestKey          `json:"request_key"`
}

type RetryInput 

type RetryInput struct {
	ThreadID     identity.ThreadID `json:"thread_id"`
	SourceTurnID identity.TurnID   `json:"source_turn_id"`
	RequestKey   RequestKey        `json:"request_key"`
}

type RunLabels 

type RunLabels struct {
	Correlation map[string]string `json:"correlation,omitempty"`
	Host        map[string]string `json:"host,omitempty"`
}

type RunMetrics 

type RunMetrics struct {
	ProviderUsage publicprovider.Usage `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"`
}

type SendInput 

type SendInput struct {
	ThreadID            identity.ThreadID             `json:"thread_id"`
	Input               UserInput                     `json:"input"`
	SupplementalContext []TurnSupplementalContextItem `json:"supplemental_context,omitempty"`
	RequestKey          RequestKey                    `json:"request_key"`
}

type SetTitleInput 

type SetTitleInput struct {
	ThreadID   identity.ThreadID `json:"thread_id"`
	Title      string            `json:"title"`
	RequestKey RequestKey        `json:"request_key"`
}

type SignalDisposition 

type SignalDisposition string
const (
	SignalContinue SignalDisposition = "continue"
	SignalWaiting  SignalDisposition = "waiting"
)

type StartupPhase added in v7.0.2 

type StartupPhase string

StartupPhase identifies storage startup work performed by Open. 

const (
	StartupPhaseMigrating StartupPhase = "migrating"
	StartupPhaseVerifying StartupPhase = "verifying"
)

type StartupProgress added in v7.0.2 

type StartupProgress interface {
	OnStartupPhase(StartupPhase)
}

StartupProgress observes changes in the storage startup phase.

type StartupProgressFunc added in v7.0.2 

type StartupProgressFunc func(StartupPhase)

StartupProgressFunc adapts a function to StartupProgress.

func (StartupProgressFunc) OnStartupPhase added in v7.0.2 

func (progress StartupProgressFunc) OnStartupPhase(phase StartupPhase)

OnStartupPhase reports one startup phase when the function is non-nil.

type StorageResetPreflight 

type StorageResetPreflight struct {
	EnvironmentID           string
	OperationID             string
	OwnershipManifestSHA256 string
	Supported               bool
}

StorageResetPreflight is safe to present before destructive confirmation.

func PreflightStorageReset 

func PreflightStorageReset(ctx context.Context, request StorageResetRequest) (StorageResetPreflight, error)

PreflightStorageReset verifies request ownership metadata and backend reset support without changing Floret records. The caller must keep every runtime Host for the selected store stopped until reset completes.

type StorageResetRequest 

type StorageResetRequest struct {
	Storage                 publicstorage.Source
	EnvironmentID           string
	OperationID             string
	OwnershipManifestSHA256 string
}

StorageResetRequest binds one destructive maintenance operation to the exact environment and host ownership manifest that selected the store.

type StorageResetResult 

type StorageResetResult struct {
	EnvironmentID           string
	OperationID             string
	OwnershipManifestSHA256 string
	PreviousDataRemoved     bool
}

StorageResetResult reports a newly initialized current-schema store.

func ResetStorage 

func ResetStorage(ctx context.Context, request StorageResetRequest) (result StorageResetResult, retErr error)

ResetStorage removes all Floret records through the backend owner, then initializes and verifies one fresh current-schema store. Repeating the same request is idempotent and never imports previous records.

type StreamObservation 

type StreamObservation struct {
	Type             StreamObservationType     `json:"type"`
	Text             string                    `json:"text,omitempty"`
	ToolCallStream   *ToolCallStream           `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"`
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id,omitempty"`
	AttemptID        string                    `json:"attempt_id,omitempty"`
	AttemptEpoch     int                       `json:"attempt_epoch,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 

func (s StreamObservation) Validate() error

type StreamObservationType 

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 

func (t StreamObservationType) Valid() bool

type ThreadActivity 

type ThreadActivity string

ThreadActivity reports whether a thread owns an accepted turn. RunProgress separately reports transient progress while its current run is advancing. 

const (
	ThreadActivityIdle   ThreadActivity = "idle"
	ThreadActivityActive ThreadActivity = "active"
)

type ThreadContextCompaction 

type ThreadContextCompaction struct {
	RunID               identity.RunID    `json:"run_id,omitempty"`
	ThreadID            identity.ThreadID `json:"thread_id,omitempty"`
	TurnID              identity.TurnID   `json:"turn_id,omitempty"`
	Step                int               `json:"step,omitempty"`
	OperationID         string            `json:"operation_id,omitempty"`
	RequestID           string            `json:"request_id,omitempty"`
	Phase               string            `json:"phase,omitempty"`
	Status              string            `json:"status,omitempty"`
	Trigger             string            `json:"trigger,omitempty"`
	Reason              string            `json:"reason,omitempty"`
	Source              string            `json:"source,omitempty"`
	TokensBefore        int64             `json:"tokens_before,omitempty"`
	TokensAfterEstimate int64             `json:"tokens_after_estimate,omitempty"`
	Error               string            `json:"error,omitempty"`
	ObservedAt          time.Time         `json:"observed_at,omitempty"`
}

type ThreadContextModel 

type ThreadContextModel struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
}

type ThreadContextPolicy 

type ThreadContextPolicy struct {
	ContextWindowTokens  int64 `json:"context_window_tokens,omitempty"`
	MaxOutputTokens      int64 `json:"max_output_tokens,omitempty"`
	ReservedOutputTokens int64 `json:"reserved_output_tokens,omitempty"`
}

type ThreadContextReader 

type ThreadContextReader interface {
	Context(context.Context, identity.ThreadID) (ThreadContextSnapshot, error)
}

ThreadContextReader exposes canonical context lifecycle facts without widening the lifecycle mutation surface of ThreadService.

type ThreadContextSnapshot 

type ThreadContextSnapshot struct {
	Model       ThreadContextModel         `json:"model,omitempty"`
	Policy      ThreadContextPolicy        `json:"policy,omitempty"`
	Usage       *observation.ContextStatus `json:"usage,omitempty"`
	UsageTotals *ThreadTokenUsageTotals    `json:"usage_totals,omitempty"`
	Compactions []ThreadContextCompaction  `json:"compactions,omitempty"`
	UpdatedAt   time.Time                  `json:"updated_at,omitempty"`
}

ThreadContextSnapshot is the canonical context and compaction projection for one thread. Compactions contain one latest lifecycle record per operation.

type ThreadInteraction 

type ThreadInteraction struct {
	ID         string                 `json:"id"`
	TurnID     identity.TurnID        `json:"turn_id"`
	RunID      identity.RunID         `json:"run_id"`
	Kind       ThreadInteractionKind  `json:"kind"`
	ToolCallID string                 `json:"tool_call_id,omitempty"`
	Resolved   bool                   `json:"resolved,omitempty"`
	Approved   *bool                  `json:"approved,omitempty"`
	Approval   *ApprovalPresentation  `json:"approval,omitempty"`
	Input      *InputPresentation     `json:"input,omitempty"`
	Resolution *InteractionResolution `json:"resolution,omitempty"`
}

ThreadInteraction is an unresolved or resolved action embedded in one item.

type ThreadInteractionKind 

type ThreadInteractionKind string
const (
	ThreadInteractionApproval ThreadInteractionKind = "approval"
	ThreadInteractionInput    ThreadInteractionKind = "input"
)

type ThreadItem 

type ThreadItem struct {
	ID     string          `json:"id"`
	TurnID identity.TurnID `json:"turn_id,omitempty"`
	RunID  identity.RunID  `json:"run_id"`
	// Ordinal is the stable one-based position in the thread presentation.
	Ordinal uint64         `json:"ordinal"`
	Kind    ThreadItemKind `json:"kind"`
	Text    string         `json:"text,omitempty"`
	// Live reports that this segment may still grow in place.
	Live        bool                      `json:"live,omitempty"`
	CreatedAt   time.Time                 `json:"created_at,omitempty"`
	Attachments []MessageAttachment       `json:"attachments,omitempty"`
	References  []MessageReference        `json:"references,omitempty"`
	Activity    *observation.ActivityItem `json:"activity,omitempty"`
	Interaction *ThreadInteraction        `json:"interaction,omitempty"`
}

ThreadItem is a directly renderable current-view item.

type ThreadItemKind 

type ThreadItemKind string

ThreadItemKind identifies one stable current-view item. 

const (
	ThreadItemUser ThreadItemKind = "user"
	// ThreadItemThinking is one ordered reasoning segment in a thread view.
	ThreadItemThinking    ThreadItemKind = "thinking"
	ThreadItemAssistant   ThreadItemKind = "assistant"
	ThreadItemTool        ThreadItemKind = "tool"
	ThreadItemInteraction ThreadItemKind = "interaction"
)

type ThreadPhase 

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

type ThreadRunPhase 

type ThreadRunPhase string

ThreadRunPhase identifies one provider-neutral active-run phase. 

const (
	ThreadRunPhasePreparing       ThreadRunPhase = "preparing"
	ThreadRunPhaseWaitingResponse ThreadRunPhase = "waiting_response"
	ThreadRunPhaseStreaming       ThreadRunPhase = "streaming"
	ThreadRunPhaseRetrying        ThreadRunPhase = "retrying"
	ThreadRunPhaseFinalizing      ThreadRunPhase = "finalizing"
	ThreadRunPhaseToolExecution   ThreadRunPhase = "tool_execution"
)

type ThreadRunProgress 

type ThreadRunProgress struct {
	Phase ThreadRunPhase `json:"phase"`
}

ThreadRunProgress is the process-local presentation of an advancing run. It is absent while the thread is idle, terminal, or waiting for interaction.

type ThreadScope 

type ThreadScope struct {
	ParentID *identity.ThreadID `json:"parent_id,omitempty"`
}

ThreadScope is a host-neutral root or direct-child inventory filter.

type ThreadService 

type ThreadService interface {
	Create(context.Context, CreateThreadInput) (ThreadView, error)
	Fork(context.Context, ForkThreadInput) (ThreadView, error)
	Delete(context.Context, DeleteThreadInput) error
	SetTitle(context.Context, SetTitleInput) (ThreadView, error)
	List(context.Context, ThreadScope) ([]ThreadSummary, error)
	View(context.Context, identity.ThreadID) (ThreadView, error)
	History(context.Context, identity.ThreadID, string, int) (HistoryPage, error)
	Send(context.Context, SendInput) (ThreadView, error)
	Respond(context.Context, RespondInput) (ThreadView, error)
	Cancel(context.Context, CancelInput) (ThreadView, error)
	Retry(context.Context, RetryInput) (ThreadView, error)
	ReorderQueue(context.Context, ReorderQueueInput) (ThreadView, error)
	DeleteQueued(context.Context, DeleteQueuedInput) (ThreadView, error)
	PromoteQueued(context.Context, PromoteQueuedInput) (ThreadView, error)
	ImportPendingInputs(context.Context, ImportPendingInputsInput) (ImportResult, error)
	Subscribe(context.Context) (*WorkspaceSubscription, error)
}

ThreadService is the only provider-backed thread lifecycle boundary.

type ThreadStatus 

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 

type ThreadSummary struct {
	ID              identity.ThreadID  `json:"id"`
	ParentThreadID  identity.ThreadID  `json:"parent_thread_id,omitempty"`
	ParentTurnID    identity.TurnID    `json:"parent_turn_id,omitempty"`
	TaskName        string             `json:"task_name,omitempty"`
	TaskDescription string             `json:"task_description,omitempty"`
	HostProfileRef  string             `json:"host_profile_ref,omitempty"`
	ForkMode        string             `json:"fork_mode,omitempty"`
	Title           string             `json:"title,omitempty"`
	TitleStatus     ThreadTitleStatus  `json:"title_status,omitempty"`
	CreatedAt       time.Time          `json:"created_at"`
	UpdatedAt       time.Time          `json:"updated_at"`
	Activity        ThreadActivity     `json:"activity"`
	Attention       AttentionSummary   `json:"attention"`
	LastOutcome     *TurnOutcome       `json:"last_outcome,omitempty"`
	TurnID          identity.TurnID    `json:"turn_id,omitempty"`
	RunID           identity.RunID     `json:"run_id,omitempty"`
	RunProgress     *ThreadRunProgress `json:"run_progress,omitempty"`
	QueueCount      int                `json:"queue_count,omitempty"`
	Failure         *ThreadTurnFailure `json:"failure,omitempty"`
	PendingInput    *InputPresentation `json:"pending_input,omitempty"`
	LastItemAt      time.Time          `json:"last_item_at,omitempty"`
	LastItemPreview string             `json:"last_item_preview,omitempty"`
}

type ThreadTitleMode 

type ThreadTitleMode string

ThreadTitleMode selects who owns durable thread title generation. 

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

type ThreadTitleStatus 

type ThreadTitleStatus string

ThreadTitleStatus is presentation metadata derived from the canonical thread journal. It does not own thread lifecycle state. 

const (
	ThreadTitleStatusUnset   ThreadTitleStatus = ""
	ThreadTitleStatusPending ThreadTitleStatus = "pending"
	ThreadTitleStatusReady   ThreadTitleStatus = "ready"
	ThreadTitleStatusFailed  ThreadTitleStatus = "failed"
)

type ThreadTokenUsageTotals 

type ThreadTokenUsageTotals struct {
	InputTokens      int64 `json:"input_tokens,omitempty"`
	OutputTokens     int64 `json:"output_tokens,omitempty"`
	CacheReadTokens  int64 `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens int64 `json:"cache_write_tokens,omitempty"`
}

ThreadTokenUsageTotals contains disjoint token totals from canonical final provider usage records across one thread.

type ThreadTurnFailure 

type ThreadTurnFailure struct {
	Code    ThreadTurnFailureCode `json:"code"`
	Message string                `json:"message"`
}

func (ThreadTurnFailure) Validate 

func (f ThreadTurnFailure) Validate() error

type ThreadTurnFailureCode 

type ThreadTurnFailureCode string
const (
	ThreadTurnFailureCancelled                ThreadTurnFailureCode = "cancelled"
	ThreadTurnFailureInterrupted              ThreadTurnFailureCode = "interrupted"
	ThreadTurnFailureProvider                 ThreadTurnFailureCode = "provider"
	ThreadTurnFailureToolDispatch             ThreadTurnFailureCode = "tool_dispatch"
	ThreadTurnFailureControlError             ThreadTurnFailureCode = "control_error"
	ThreadTurnFailureEffectOutcomeUnknown     ThreadTurnFailureCode = "effect_outcome_unknown"
	ThreadTurnFailureAuthorizationUnavailable ThreadTurnFailureCode = "authorization_unavailable"
	ThreadTurnFailureAuthorizationContract    ThreadTurnFailureCode = "authorization_contract"
	ThreadTurnFailureStorage                  ThreadTurnFailureCode = "storage"
	ThreadTurnFailureEngineContract           ThreadTurnFailureCode = "engine_contract"
	ThreadTurnFailureContextPrefixDrift       ThreadTurnFailureCode = "context_prefix_drift"
	ThreadTurnFailureLegacyUnclassified       ThreadTurnFailureCode = "legacy_unclassified"
)

func (ThreadTurnFailureCode) Valid 

func (c ThreadTurnFailureCode) Valid() bool

type ThreadView 

type ThreadView struct {
	ThreadID     identity.ThreadID   `json:"thread_id"`
	ViewVersion  uint64              `json:"view_version"`
	Activity     ThreadActivity      `json:"activity"`
	Attention    AttentionSummary    `json:"attention"`
	LastOutcome  *TurnOutcome        `json:"last_outcome,omitempty"`
	Failure      *ThreadTurnFailure  `json:"failure,omitempty"`
	TurnID       identity.TurnID     `json:"turn_id,omitempty"`
	RunID        identity.RunID      `json:"run_id,omitempty"`
	RunProgress  *ThreadRunProgress  `json:"run_progress,omitempty"`
	Items        []ThreadItem        `json:"items,omitempty"`
	Queue        []QueuedInput       `json:"queue,omitempty"`
	Interactions []ThreadInteraction `json:"interactions,omitempty"`
}

ThreadView is the complete, replaceable presentation for one thread. Its version is process-local notification ordering, not a durable journal cursor.

type ToolCallStream 

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

type ToolSurface 

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

type ToolSurfaceProvider 

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

type ToolSurfaceRequest 

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

type TurnInput 

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

func (TurnInput) Validate 

func (i TurnInput) Validate() error

type TurnLimits 

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

type TurnOutcome 

type TurnOutcome string

TurnOutcome is a terminal outcome rendered on one turn, never as thread failure. 

const (
	TurnOutcomeCompleted   TurnOutcome = "completed"
	TurnOutcomeFailed      TurnOutcome = "failed"
	TurnOutcomeCancelled   TurnOutcome = "cancelled"
	TurnOutcomeInterrupted TurnOutcome = "interrupted"
)

type TurnResult 

type TurnResult struct {
	ThreadID           identity.ThreadID              `json:"thread_id"`
	TurnID             identity.TurnID                `json:"turn_id"`
	RunID              identity.RunID                 `json:"-"`
	Status             TurnStatus                     `json:"status"`
	Output             string                         `json:"output,omitempty"`
	Failure            *ThreadTurnFailure             `json:"failure,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"`
	Replayed           bool                           `json:"replayed,omitempty"`
}

func (TurnResult) Validate 

func (r TurnResult) Validate() error

type TurnSignal 

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    *tools.ActivityPresentation `json:"activity,omitempty"`
	OutputText  string                      `json:"output_text,omitempty"`
	ArgsHash    string                      `json:"args_hash,omitempty"`
	Labels      map[string]string           `json:"labels,omitempty"`
}

func ProjectCoreControlSignal 

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

ProjectCoreControlSignal projects ask_user calls into Floret control signals.

type TurnSignalSpec 

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

type TurnStatus 

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

func (TurnStatus) IsTerminal 

func (s TurnStatus) IsTerminal() bool

func (TurnStatus) Valid 

func (s TurnStatus) Valid() bool

type TurnSupplementalContextItem 

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

type UserInput 

type UserInput = TurnInput

UserInput is one user-authored thread input.

type WorkspaceSubscription 

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

WorkspaceSubscription receives replaceable current views.

func (*WorkspaceSubscription) Close 

func (subscription *WorkspaceSubscription) Close()

func (*WorkspaceSubscription) Next 

func (subscription *WorkspaceSubscription) Next(ctx context.Context) (ThreadView, error)

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.