runtime

package
v2.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 35 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 (
	CoreControlAskUser      = tools.ControlAskUser
	CoreControlTaskComplete = tools.ControlTaskComplete
)
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
)

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 v2 contract.
	ErrUnsupportedSchema = errors.New("unsupported floret logical schema")
)
View Source 
var (
	// 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 = errors.New("floret store is closed")
	// 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 (
	ErrInvalidThreadTurnCursor = errors.New("floret thread turn cursor is invalid")
	ErrStaleThreadTurnCursor   = errors.New("floret thread turn cursor is stale")
)
View Source 
var ErrInvalidThreadInventoryCursor = errors.New("floret thread inventory cursor is invalid")

Functions

func CoreControlDefinitions 

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 

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 

func ProviderSafeCoreControlText(signal TurnSignal) string

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

Types

type ActivePendingToolCompletion added in v2.1.0 

type ActivePendingToolCompletion struct {
	CompletionRequestID string
	Target              ActivePendingToolTarget
	ContinuationTurnID  TurnID
	ContinuationRunID   RunID
	Status              PendingToolCompletionStatus
	Summary             string
	Output              string
	Input               TurnInput
	Labels              RunLabels
}

ActivePendingToolCompletion describes a provider continuation for pending work on the thread already bound by a TurnRunner.

type ActivePendingToolSettlement added in v2.1.0 

type ActivePendingToolSettlement struct {
	Target   ActivePendingToolTarget
	Status   PendingToolSettlementStatus
	Summary  string
	Output   string
	Activity *observation.ActivityPresentation
}

ActivePendingToolSettlement records a pending tool outcome on the thread already bound by a TurnRunner without resuming provider execution.

type ActivePendingToolTarget added in v2.1.0 

type ActivePendingToolTarget struct {
	TurnID          TurnID
	RunID           RunID
	ToolCallID      string
	ToolName        string
	Handle          string
	EffectAttemptID string
}

ActivePendingToolTarget identifies one pending tool on the thread already bound by a TurnRunner.

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 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 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 AgentTodo 

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

type AgentTodoStatus 

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

func (AgentTodoStatus) Valid 

func (s AgentTodoStatus) Valid() bool

type AgentTodoUpdateRequest added in v2.1.0 

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

AgentTodoUpdateRequest updates canonical Agent todos after ThreadID is bound.

type ApprovalDecision 

type ApprovalDecision string
const (
	ApprovalDecisionApprove ApprovalDecision = "approve"
	ApprovalDecisionReject  ApprovalDecision = "reject"
)

type ApprovalDecisionReceipt 

type ApprovalDecisionReceipt struct {
	DecisionID             string           `json:"decision_id"`
	ApprovalID             string           `json:"approval_id"`
	RootThreadID           ThreadID         `json:"root_thread_id"`
	Decision               ApprovalDecision `json:"decision"`
	State                  string           `json:"state"`
	Reason                 string           `json:"reason,omitempty"`
	AuthorizationProofHash string           `json:"authorization_proof_hash,omitempty"`
	QueueGeneration        int64            `json:"queue_generation"`
	QueueRevision          int64            `json:"queue_revision"`
	ApprovalRevision       int64            `json:"approval_revision"`
	SubmittedAt            time.Time        `json:"submitted_at"`
	ResolvedAt             time.Time        `json:"resolved_at,omitempty"`
}

func (ApprovalDecisionReceipt) Validate 

func (r ApprovalDecisionReceipt) Validate() error

type ApprovalIdentity 

type ApprovalIdentity struct {
	ApprovalID      string   `json:"approval_id"`
	ThreadID        ThreadID `json:"thread_id"`
	TurnID          TurnID   `json:"turn_id"`
	RunID           RunID    `json:"run_id"`
	ToolCallID      string   `json:"tool_call_id"`
	EffectAttemptID string   `json:"effect_attempt_id"`
}

func (ApprovalIdentity) Validate 

func (i ApprovalIdentity) Validate() error

type ApprovalQueue 

type ApprovalQueue struct {
	RootThreadID      ThreadID         `json:"root_thread_id"`
	Generation        int64            `json:"generation"`
	Revision          int64            `json:"revision"`
	CurrentApprovalID string           `json:"current_approval_id,omitempty"`
	Items             []ApprovalRecord `json:"items"`
	GeneratedAt       time.Time        `json:"generated_at"`
}

func (ApprovalQueue) Validate 

func (q ApprovalQueue) Validate() error

type ApprovalRecord 

type ApprovalRecord struct {
	ApprovalID             string             `json:"approval_id,omitempty"`
	RootThreadID           ThreadID           `json:"root_thread_id,omitempty"`
	ParentThreadID         ThreadID           `json:"parent_thread_id,omitempty"`
	ToolCallID             string             `json:"tool_call_id,omitempty"`
	EffectAttemptID        string             `json:"effect_attempt_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"`
	QueueSequence          int64              `json:"queue_sequence,omitempty"`
	DecisionID             string             `json:"decision_id,omitempty"`
	RequestedAt            time.Time          `json:"requested_at,omitempty"`
	UpdatedAt              time.Time          `json:"updated_at,omitempty"`
	ResolvedAt             time.Time          `json:"resolved_at,omitempty"`
	ArgsHash               string             `json:"args_hash,omitempty"`
	RequestFingerprint     string             `json:"request_fingerprint,omitempty"`
	AuthorizationProofHash string             `json:"authorization_proof_hash,omitempty"`
	Resources              []ApprovalResource `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 (ApprovalRecord) Validate 

func (p ApprovalRecord) Validate() error

type ApprovalResolutionRequest added in v2.1.0 

type ApprovalResolutionRequest struct {
	DecisionID               string
	ExpectedGeneration       int64
	ExpectedRevision         int64
	ExpectedCurrent          ApprovalIdentity
	ExpectedApprovalRevision int64
	Decision                 ApprovalDecision
}

ApprovalResolutionRequest describes one approval decision after the root ThreadID is bound by a TurnRunner. ExpectedCurrent.ThreadID identifies the exact root or descendant execution that requested approval.

type ApprovalResource 

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

func (ApprovalResource) Validate 

func (r ApprovalResource) Validate() error

type ArtifactContent 

type ArtifactContent struct {
	Ref  ArtifactRef `json:"ref"`
	Text string      `json:"text"`
}

func (ArtifactContent) Validate 

func (c ArtifactContent) Validate() error

Validate checks one public artifact content result.

type ArtifactID 

type ArtifactID string

type ArtifactRef 

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

func (ArtifactRef) Validate 

func (r ArtifactRef) Validate() error

Validate checks one public artifact reference.

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 CapabilityOptions 

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

type CloseSubAgent 

type CloseSubAgent struct {
	CloseOperationID string
	ChildThreadID    ThreadID
	Reason           string
}

CloseSubAgent describes child closure after ParentThreadID is bound.

type CloseSubAgentRequest 

type CloseSubAgentRequest struct {
	CloseOperationID string
	ParentThreadID   ThreadID
	ChildThreadID    ThreadID
	Reason           string
}

type CommittedCleanupError 

type CommittedCleanupError struct {
	ThreadID 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 CompactThreadRequest 

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

type CompactThreadResult 

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"`
	Replayed         bool                         `json:"replayed,omitempty"`
}

func (CompactThreadResult) Validate 

func (r CompactThreadResult) Validate() 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 CreateIntentID 

type CreateIntentID string

type CreateThreadRequest 

type CreateThreadRequest struct {
	ThreadID       ThreadID
	CreateIntentID CreateIntentID
}

func (CreateThreadRequest) Validate 

func (r CreateThreadRequest) Validate() error

Validate checks the explicit identities required for a durable root create.

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           ThreadID  `json:"thread_id"`
	TurnID             TurnID    `json:"turn_id"`
	RunID              RunID     `json:"run_id"`
	ToolCallID         string    `json:"tool_call_id"`
	LeaseOwnerID       string    `json:"lease_owner_id"`
	LeaseGeneration    int64     `json:"lease_generation"`
	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           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"`
	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"`
	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"`
	LeaseOwnerID       string               `json:"lease_owner_id"`
	LeaseGeneration    int64                `json:"lease_generation"`
	ObservedHeartbeat  int64                `json:"observed_heartbeat"`
}

type EffectDispatchResult 

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

type Event 

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            []publicprovider.Source           `json:"sources,omitempty"`
	Metadata           map[string]any                    `json:"metadata,omitempty"`
	Timestamp          time.Time                         `json:"timestamp,omitempty"`
}

func (Event) Validate 

func (e Event) Validate() error

type EventSink 

type EventSink interface {
	EmitEvent(Event)
}

type ForkOperationID 

type ForkOperationID string

type ForkThreadRequest 

type ForkThreadRequest struct {
	OperationID         ForkOperationID
	SourceThreadID      ThreadID
	DestinationThreadID ThreadID
}

type ForkThreadResult 

type ForkThreadResult struct {
	OperationID ForkOperationID `json:"operation_id"`
	Thread      ThreadSummary   `json:"thread"`
}

func (ForkThreadResult) Validate 

func (r ForkThreadResult) Validate() error

Validate checks one public fork result.

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 v2 logical schema, initializes an empty Backend, and transfers exclusive backend lifecycle ownership to a new Host.

func (*Host) Close 

func (host *Host) Close() error

Close waits for active runtime work, then closes the owned Backend. It is idempotent.

func (*Host) InterruptedTurnRecovery 

func (host *Host) InterruptedTurnRecovery(ctx context.Context, target InterruptedTurnRecoveryTarget, sink EventSink) (*InterruptedTurnRecovery, error)

InterruptedTurnRecovery binds the current durable interrupted lease proof for one exact root or child thread.

func (*Host) PendingToolRecovery 

func (host *Host) PendingToolRecovery(ctx context.Context, target PendingToolRecoveryTarget, sink EventSink) (*PendingToolRecovery, error)

PendingToolRecovery binds recovery to one exact root or child pending tool.

func (*Host) SubAgentManager 

func (host *Host) SubAgentManager(ctx context.Context, parentThreadID ThreadID, agent *Agent) (*SubAgentManager, error)

SubAgentManager binds child lifecycle to one parent and one immutable Agent.

func (*Host) SubAgentReader 

func (host *Host) SubAgentReader(ctx context.Context, parentThreadID ThreadID) (*SubAgentReader, error)

SubAgentReader binds child reads to one exact parent.

func (*Host) ThreadCompactor 

func (host *Host) ThreadCompactor(ctx context.Context, threadID ThreadID, agent *Agent) (*ThreadCompactor, error)

ThreadCompactor binds one immutable Agent to compaction for a root thread.

func (*Host) ThreadCreator 

func (host *Host) ThreadCreator(threadID ThreadID, createIntentID CreateIntentID) (*ThreadCreator, error)

ThreadCreator binds root-thread and create-intent identity before creation.

func (*Host) ThreadDeleter 

func (host *Host) ThreadDeleter(ctx context.Context, threadID ThreadID) (*ThreadDeleter, error)

ThreadDeleter binds deletion to one root thread tree.

func (*Host) ThreadForker 

func (host *Host) ThreadForker(ctx context.Context, threadID ThreadID) (*ThreadForker, error)

ThreadForker binds fork source identity to one root thread.

func (*Host) ThreadInventory 

func (host *Host) ThreadInventory(ctx context.Context) (*ThreadInventory, error)

ThreadInventory issues canonical root-thread enumeration authority.

func (*Host) ThreadReader 

func (host *Host) ThreadReader(ctx context.Context, threadID ThreadID) (*ThreadReader, error)

ThreadReader binds all canonical reads to one root thread.

func (*Host) ThreadTitleEditor 

func (host *Host) ThreadTitleEditor(ctx context.Context, threadID ThreadID) (*ThreadTitleEditor, error)

ThreadTitleEditor binds title mutation to one root thread.

func (*Host) TurnRunner 

func (host *Host) TurnRunner(ctx context.Context, threadID ThreadID, agent *Agent) (*TurnRunner, error)

TurnRunner binds one immutable Agent to one root thread.

type InterruptedTurnRecovery 

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

InterruptedTurnRecovery owns one exact interrupted lease proof.

func (*InterruptedTurnRecovery) Recover 

func (recovery *InterruptedTurnRecovery) Recover(ctx context.Context) (RecoverInterruptedTurnResult, error)

Recover atomically finalizes the exact interrupted lease proof bound during issuance.

type InterruptedTurnRecoveryTarget 

type InterruptedTurnRecoveryTarget struct {
	ParentThreadID ThreadID
	ThreadID       ThreadID
}

InterruptedTurnRecoveryTarget identifies a root or canonical child whose current interrupted lease proof will be bound during issuance.

func (InterruptedTurnRecoveryTarget) Validate 

func (target InterruptedTurnRecoveryTarget) Validate() error

Validate checks the complete thread relationship identity.

type ListRootThreadsRequest 

type ListRootThreadsRequest struct {
	Cursor ThreadInventoryCursor `json:"cursor,omitempty"`
	Limit  int                   `json:"limit,omitempty"`
}

type ListSubAgentActivityTimelineRequest 

type ListSubAgentActivityTimelineRequest struct {
	ParentThreadID ThreadID
	Meta           observation.ActivityRunMeta
}

type ListSubAgentPendingToolSettlementTargetsRequest 

type ListSubAgentPendingToolSettlementTargetsRequest struct {
	ParentThreadID ThreadID `json:"parent_thread_id"`
	ChildThreadID  ThreadID `json:"child_thread_id"`
}

ListSubAgentPendingToolSettlementTargetsRequest identifies one direct child whose canonical pending tool targets should be read.

type ListThreadDetailEventsRequest 

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

type ListThreadTurnsRequest 

type ListThreadTurnsRequest struct {
	ThreadID     ThreadID          `json:"thread_id"`
	BeforeCursor *ThreadTurnCursor `json:"before_cursor,omitempty"`
	SinceCursor  *ThreadTurnCursor `json:"since_cursor,omitempty"`
	Tail         int               `json:"tail,omitempty"`
	Limit        int               `json:"limit,omitempty"`
}

type LoopLimits 

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

type ManualCompactionPollRequest 

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 

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
}

Options configures one runtime Host.

type PendingToolCompletionRequest 

type PendingToolCompletionRequest struct {
	CompletionRequestID string
	Target              PendingToolSettlementTarget
	ContinuationTurnID  TurnID
	ContinuationRunID   RunID
	Status              PendingToolCompletionStatus
	Summary             string
	Output              string
	Input               TurnInput
	Labels              RunLabels
}

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

type PendingToolCompletionResult 

type PendingToolCompletionResult struct {
	CompletionRequestID string      `json:"completion_request_id"`
	ThreadID            ThreadID    `json:"thread_id"`
	TurnID              TurnID      `json:"turn_id"`
	RunID               RunID       `json:"run_id"`
	Status              TurnStatus  `json:"status"`
	Replayed            bool        `json:"replayed,omitempty"`
	Turn                *TurnResult `json:"turn,omitempty"`
}

PendingToolCompletionResult reports the one durable continuation admission. Turn is present only once that continuation has reached a terminal state.

func (PendingToolCompletionResult) Validate 

func (r PendingToolCompletionResult) Validate() error

type PendingToolCompletionStatus 

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 PendingToolRecovery 

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

PendingToolRecovery settles one exact target without provider execution.

func (*PendingToolRecovery) Settle 

func (recovery *PendingToolRecovery) Settle(ctx context.Context, request PendingToolRecoveryRequest) (PendingToolSettlementResult, error)

Settle records the bound pending tool outcome exactly once or replays the same durable settlement.

type PendingToolRecoveryRequest 

type PendingToolRecoveryRequest struct {
	Status   PendingToolSettlementStatus
	Summary  string
	Output   string
	Activity *observation.ActivityPresentation
}

PendingToolRecoveryRequest contains only the host-owned outcome for a target already bound by PendingToolRecoveryTarget.

type PendingToolRecoveryTarget 

type PendingToolRecoveryTarget struct {
	ParentThreadID ThreadID
	Target         PendingToolSettlementTarget
}

PendingToolRecoveryTarget binds one exact pending tool and, for a child thread, its canonical parent.

func (PendingToolRecoveryTarget) Validate 

func (target PendingToolRecoveryTarget) Validate() error

Validate checks the complete recovery authority identity.

type PendingToolSettlementRequest 

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 

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 

func (r PendingToolSettlementResult) Validate() error

type PendingToolSettlementStatus 

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 

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"`
	EffectAttemptID string   `json:"effect_attempt_id,omitempty"`
}

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

func (PendingToolSettlementTarget) Validate 

func (t PendingToolSettlementTarget) Validate() error

Validate checks the exact identity required to settle one pending tool.

type ProjectThreadTurnRequest 

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

type PromptScopeID 

type PromptScopeID string

type PublishSubAgentPendingToolCompletion 

type PublishSubAgentPendingToolCompletion struct {
	InputRequestID string
	ChildThreadID  ThreadID
	Target         PendingToolSettlementTarget
	Status         PendingToolCompletionStatus
	Summary        string
	Output         string
	Input          TurnInput
	Labels         RunLabels
}

PublishSubAgentPendingToolCompletion describes host-owned child continuation input after ParentThreadID is bound.

type PublishSubAgentPendingToolCompletionRequest 

type PublishSubAgentPendingToolCompletionRequest struct {
	InputRequestID string
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	Target         PendingToolSettlementTarget
	Status         PendingToolCompletionStatus
	Summary        string
	Output         string
	Input          TurnInput
	Labels         RunLabels
}

type ReadApprovalQueueRequest 

type ReadApprovalQueueRequest struct {
	ThreadID ThreadID
}

type ReadArtifactRequest 

type ReadArtifactRequest struct {
	ThreadID   ThreadID   `json:"thread_id"`
	ArtifactID ArtifactID `json:"artifact_id"`
}

type ReadSubAgentDetailRequest 

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

type ReadThreadTurnRequest 

type ReadThreadTurnRequest struct {
	ThreadID ThreadID
	TurnID   TurnID
}

ReadThreadTurnRequest identifies one canonical turn on a thread's current active path. It is a Go host contract, not a wire schema.

type ReadTurnProjectionRequest 

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 RecoverInterruptedTurnResult 

type RecoverInterruptedTurnResult struct {
	ThreadID ThreadID           `json:"thread_id"`
	TurnID   TurnID             `json:"turn_id"`
	RunID    RunID              `json:"run_id"`
	Status   TurnStatus         `json:"status"`
	Failure  *ThreadTurnFailure `json:"failure,omitempty"`
	Replayed bool               `json:"replayed"`
}

func (RecoverInterruptedTurnResult) Validate 

func (r RecoverInterruptedTurnResult) Validate() error

Validate checks one public interrupted-turn recovery result.

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 ResolveApprovalRequest 

type ResolveApprovalRequest struct {
	DecisionID               string           `json:"decision_id"`
	ExpectedRootThreadID     ThreadID         `json:"expected_root_thread_id"`
	ExpectedGeneration       int64            `json:"expected_generation"`
	ExpectedRevision         int64            `json:"expected_revision"`
	ExpectedCurrent          ApprovalIdentity `json:"expected_current"`
	ExpectedApprovalRevision int64            `json:"expected_approval_revision"`
	Decision                 ApprovalDecision `json:"decision"`
}

func (ResolveApprovalRequest) Validate 

func (r ResolveApprovalRequest) Validate() error

type ResolveApprovalResult 

type ResolveApprovalResult struct {
	Receipt  ApprovalDecisionReceipt `json:"receipt"`
	Queue    ApprovalQueue           `json:"queue"`
	Approval ApprovalRecord          `json:"approval"`
	Replayed bool                    `json:"replayed,omitempty"`
}

func (ResolveApprovalResult) Validate 

func (r ResolveApprovalResult) Validate() error

type RetryRequest added in v2.1.0 

type RetryRequest struct {
	Reason string
	Labels RunLabels
}

RetryRequest describes a retry after ThreadID and Agent are bound.

type RetryTurnRequest 

type RetryTurnRequest struct {
	ThreadID ThreadID
	Reason   string
	Labels   RunLabels
}

type RootThreadsPage 

type RootThreadsPage struct {
	Threads     []ThreadSummary       `json:"threads"`
	NextCursor  ThreadInventoryCursor `json:"next_cursor,omitempty"`
	HasMore     bool                  `json:"has_more,omitempty"`
	GeneratedAt time.Time             `json:"generated_at"`
}

func (RootThreadsPage) Validate 

func (p RootThreadsPage) Validate() error

type RunID 

type RunID string

type RunLabels 

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

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"`
}

RunMetrics summarizes the observable work completed by a run.

type RunTurnRequest 

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

func (RunTurnRequest) Validate 

func (r RunTurnRequest) Validate() error

Validate checks the provider-independent request contract before admission. Host execution repeats this validation and additionally checks bound authority and provider-specific capabilities.

type SendSubAgentInput 

type SendSubAgentInput struct {
	InputRequestID string
	ChildThreadID  ThreadID
	Message        string
	Attachments    []MessageAttachment
	References     []MessageReference
	Interrupt      bool
	Labels         RunLabels
}

SendSubAgentInput describes child input after ParentThreadID is bound.

type SendSubAgentInputRequest 

type SendSubAgentInputRequest struct {
	InputRequestID string
	ParentThreadID ThreadID
	ChildThreadID  ThreadID
	Message        string
	Attachments    []MessageAttachment
	References     []MessageReference
	Interrupt      bool
	Labels         RunLabels
}

type SetThreadTitleRequest 

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

type SignalDisposition 

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 SpawnSubAgent 

type SpawnSubAgent struct {
	PublicationID   string
	ParentTurnID    TurnID
	ThreadID        ThreadID
	TaskName        string
	TaskDescription string
	Message         string
	Attachments     []MessageAttachment
	References      []MessageReference
	HostProfileRef  string
	ForkMode        SubAgentForkMode
	Labels          RunLabels
}

SpawnSubAgent describes child creation after ParentThreadID is bound.

type SpawnSubAgentRequest 

type SpawnSubAgentRequest struct {
	PublicationID   string
	ParentThreadID  ThreadID
	ParentTurnID    TurnID
	ThreadID        ThreadID
	TaskName        string
	TaskDescription string
	Message         string
	Attachments     []MessageAttachment
	References      []MessageReference
	HostProfileRef  string
	ForkMode        SubAgentForkMode
	Labels          RunLabels
}

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"`
	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 SubAgentActivityTimelineResult 

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

func (SubAgentActivityTimelineResult) Validate 

func (r SubAgentActivityTimelineResult) Validate() error

Validate checks one public SubAgent activity projection.

type SubAgentDetail 

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"`
}

func (SubAgentDetail) Validate 

func (d SubAgentDetail) Validate() error

Validate checks one public SubAgent detail page.

type SubAgentDetailRequest 

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

SubAgentDetailRequest identifies one child after ParentThreadID is bound.

type SubAgentForkMode 

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

type SubAgentManager 

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

SubAgentManager owns child lifecycle for one exact parent.

func (*SubAgentManager) Close 

func (manager *SubAgentManager) Close(ctx context.Context, request CloseSubAgent) (SubAgentSnapshot, error)

Close closes one child of the bound parent.

func (*SubAgentManager) PublishPendingToolCompletion 

func (manager *SubAgentManager) PublishPendingToolCompletion(ctx context.Context, request PublishSubAgentPendingToolCompletion) (SubAgentSnapshot, error)

PublishPendingToolCompletion admits one host-owned child continuation.

func (*SubAgentManager) SendInput 

func (manager *SubAgentManager) SendInput(ctx context.Context, request SendSubAgentInput) (SubAgentSnapshot, error)

SendInput appends or interrupts with one child input.

func (*SubAgentManager) SettlePendingTool added in v2.1.0 

func (manager *SubAgentManager) SettlePendingTool(ctx context.Context, request PendingToolSettlementRequest) (PendingToolSettlementResult, error)

SettlePendingTool records one host-owned pending tool outcome for a direct child of the bound parent without resuming provider execution.

func (*SubAgentManager) Spawn 

func (manager *SubAgentManager) Spawn(ctx context.Context, request SpawnSubAgent) (SubAgentSnapshot, error)

Spawn creates or replays one child publication.

func (*SubAgentManager) Wait 

func (manager *SubAgentManager) Wait(ctx context.Context, request WaitSubAgents) (WaitSubAgentsResult, error)

Wait waits for selected children of the bound parent.

type SubAgentReader 

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

SubAgentReader reads descendants of one exact parent.

func (*SubAgentReader) ActivityTimeline 

func (reader *SubAgentReader) ActivityTimeline(ctx context.Context, meta observation.ActivityRunMeta) (SubAgentActivityTimelineResult, error)

ActivityTimeline returns the canonical activity projection for the bound parent and supplied run metadata.

func (*SubAgentReader) List 

func (reader *SubAgentReader) List(ctx context.Context) ([]SubAgentSnapshot, error)

List returns direct children of the bound parent.

func (*SubAgentReader) ListPendingToolTargets added in v2.1.0 

func (reader *SubAgentReader) ListPendingToolTargets(ctx context.Context, childThreadID ThreadID) ([]PendingToolSettlementTarget, error)

ListPendingToolTargets returns unsettled host-owned work for a direct child of the bound parent.

func (*SubAgentReader) ListTurns added in v2.1.0 

func (reader *SubAgentReader) ListTurns(ctx context.Context, childThreadID ThreadID, request ThreadTurnsRequest) (ThreadTurnsPage, error)

ListTurns returns one canonical turn page from a direct child of the bound parent.

func (*SubAgentReader) ReadArtifact added in v2.1.0 

func (reader *SubAgentReader) ReadArtifact(ctx context.Context, childThreadID ThreadID, artifactID ArtifactID) (ArtifactContent, error)

ReadArtifact returns one artifact from a direct child of the bound parent.

func (*SubAgentReader) ReadDetail 

func (reader *SubAgentReader) ReadDetail(ctx context.Context, request SubAgentDetailRequest) (SubAgentDetail, error)

ReadDetail returns canonical detail for one child of the bound parent.

func (*SubAgentReader) ReadTurn added in v2.1.0 

func (reader *SubAgentReader) ReadTurn(ctx context.Context, childThreadID ThreadID, turnID TurnID) (ThreadTurnSnapshot, error)

ReadTurn returns one canonical turn from a direct child of the bound parent.

type SubAgentSnapshot 

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"`
}

func (SubAgentSnapshot) Validate 

func (s SubAgentSnapshot) Validate() error

Validate checks one self-contained public SubAgent projection.

type SubAgentStatus 

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"
	SubAgentStatusClosing     SubAgentStatus = "closing"
	SubAgentStatusClosed      SubAgentStatus = "closed"
)

type ThreadAgentTodoState 

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"`
}

func (ThreadAgentTodoState) Validate 

func (s ThreadAgentTodoState) Validate() error

Validate checks one canonical Agent todo projection.

type ThreadCompactionRequest 

type ThreadCompactionRequest struct {
	RequestID string
	Source    string
	Labels    RunLabels
	Limits    TurnLimits
	Reasoning config.ReasoningSelection
}

ThreadCompactionRequest describes compaction after ThreadID is bound.

type ThreadCompactor 

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

ThreadCompactor owns provider-backed compaction for one exact thread.

func (*ThreadCompactor) Compact 

func (compactor *ThreadCompactor) Compact(ctx context.Context, request ThreadCompactionRequest) (CompactThreadResult, error)

Compact compacts the bound thread.

type ThreadContextSnapshot 

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 

func (s ThreadContextSnapshot) Validate() error

type ThreadControlSignal 

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 ThreadCreator 

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

ThreadCreator is exact root-thread creation authority.

func (*ThreadCreator) Create 

func (creator *ThreadCreator) Create(ctx context.Context) (ThreadSummary, error)

Create creates or replays the bound root thread.

type ThreadDeleter 

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

ThreadDeleter is deletion authority for one exact root thread tree.

func (*ThreadDeleter) Delete 

func (deleter *ThreadDeleter) Delete(ctx context.Context) error

Delete deletes or replays deletion of the bound root thread tree.

type ThreadDetailApproval 

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 

type ThreadDetailCompaction struct {
	OperationID         string            `json:"operation_id,omitempty"`
	RequestID           string            `json:"request_id,omitempty"`
	Source              string            `json:"source,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 

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 

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 

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 

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"`
}

func (ThreadDetailEvents) Validate 

func (p ThreadDetailEvents) Validate() error

Validate checks one public detail-event page.

type ThreadDetailMessage 

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"`
	References  []MessageReference                `json:"references,omitempty"`
	Reasoning   string                            `json:"reasoning,omitempty"`
	Activity    *observation.ActivityPresentation `json:"activity,omitempty"`
}

type ThreadDetailRequest added in v2.1.0 

type ThreadDetailRequest struct {
	AfterOrdinal int64
	Limit        int
	IncludeRaw   bool
}

ThreadDetailRequest selects a canonical detail-event page after ThreadID is bound.

type ThreadDetailToolCall 

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 

type ThreadDetailToolResult struct {
	CallID          string       `json:"call_id,omitempty"`
	ToolName        string       `json:"tool_name,omitempty"`
	EffectAttemptID string       `json:"effect_attempt_id,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 

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

type ThreadForkRequest 

type ThreadForkRequest struct {
	OperationID         ForkOperationID
	DestinationThreadID ThreadID
}

ThreadForkRequest describes a fork after the source thread is bound.

type ThreadForker 

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

ThreadForker is fork authority for one exact source thread.

func (*ThreadForker) Fork 

func (forker *ThreadForker) Fork(ctx context.Context, request ThreadForkRequest) (ForkThreadResult, error)

Fork creates or replays a fork from the bound source.

type ThreadID 

type ThreadID string

type ThreadInventory 

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

ThreadInventory is composition-owned root-thread enumeration authority.

func (*ThreadInventory) List 

func (inventory *ThreadInventory) List(ctx context.Context, request ListRootThreadsRequest) (RootThreadsPage, error)

List returns one stable page of canonical root threads.

type ThreadInventoryCursor 

type ThreadInventoryCursor string

ThreadInventoryCursor is an opaque position in the canonical root-thread inventory. Hosts may persist and compare the token, but must not parse it.

type ThreadOverview 

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

func (ThreadOverview) Validate 

func (o ThreadOverview) Validate() error

Validate checks the self-contained public overview shape.

type ThreadPhase 

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

func (ThreadPhase) Valid 

func (p ThreadPhase) Valid() bool

Valid reports whether the phase is part of the public thread lifecycle.

type ThreadReader 

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

ThreadReader is read authority for one exact root thread.

func (*ThreadReader) ListDetailEvents added in v2.1.0 

func (reader *ThreadReader) ListDetailEvents(ctx context.Context, request ThreadDetailRequest) (ThreadDetailEvents, error)

ListDetailEvents returns one canonical detail-event page for the bound thread.

func (*ThreadReader) ListPendingToolTargets added in v2.1.0 

func (reader *ThreadReader) ListPendingToolTargets(ctx context.Context) ([]PendingToolSettlementTarget, error)

ListPendingToolTargets returns unsettled host-owned work for the bound thread.

func (*ThreadReader) ListTurns added in v2.1.0 

func (reader *ThreadReader) ListTurns(ctx context.Context, request ThreadTurnsRequest) (ThreadTurnsPage, error)

ListTurns returns one canonical turn page for the bound thread.

func (*ThreadReader) Read 

func (reader *ThreadReader) Read(ctx context.Context) (ThreadSnapshot, error)

Read returns the current canonical thread snapshot.

func (*ThreadReader) ReadAgentTodos added in v2.1.0 

func (reader *ThreadReader) ReadAgentTodos(ctx context.Context) (ThreadAgentTodoState, error)

ReadAgentTodos returns the canonical Agent todo state for the bound thread.

func (*ThreadReader) ReadApprovalQueue added in v2.1.0 

func (reader *ThreadReader) ReadApprovalQueue(ctx context.Context) (ApprovalQueue, error)

ReadApprovalQueue returns the canonical approval queue rooted at the bound thread.

func (*ThreadReader) ReadArtifact added in v2.1.0 

func (reader *ThreadReader) ReadArtifact(ctx context.Context, artifactID ArtifactID) (ArtifactContent, error)

ReadArtifact returns one artifact owned by the bound thread.

func (*ThreadReader) ReadContext added in v2.1.0 

func (reader *ThreadReader) ReadContext(ctx context.Context) (ThreadContextSnapshot, error)

ReadContext returns canonical context usage and compaction state for the bound thread.

func (*ThreadReader) ReadOverview added in v2.1.0 

func (reader *ThreadReader) ReadOverview(ctx context.Context) (ThreadOverview, error)

ReadOverview returns the bound thread and its latest canonical turn.

func (*ThreadReader) ReadProjection added in v2.1.0 

func (reader *ThreadReader) ReadProjection(ctx context.Context, turnID TurnID, runID RunID) (ThreadTurnProjection, error)

ReadProjection rebuilds one canonical turn projection from the bound thread.

func (*ThreadReader) ReadTurn 

func (reader *ThreadReader) ReadTurn(ctx context.Context, turnID TurnID) (ThreadTurnSnapshot, error)

ReadTurn returns one canonical turn from the bound thread.

type ThreadSnapshot 

type ThreadSnapshot struct {
	ID               ThreadID          `json:"id"`
	Title            string            `json:"title,omitempty"`
	TitleStatus      ThreadTitleStatus `json:"title_status,omitempty"`
	TitleSource      ThreadTitleSource `json:"title_source,omitempty"`
	TitleUpdatedAt   time.Time         `json:"title_updated_at,omitempty"`
	TitleError       string            `json:"title_error,omitempty"`
	TitleGeneration  int64             `json:"title_generation,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"`
}

func (ThreadSnapshot) Validate 

func (s ThreadSnapshot) Validate() error

Validate checks the complete public thread snapshot contract.

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"
)

func (ThreadStatus) Valid 

func (s ThreadStatus) Valid() bool

Valid reports whether the status is part of the public thread lifecycle.

type ThreadSummary 

type ThreadSummary struct {
	ID               ThreadID          `json:"id"`
	Title            string            `json:"title,omitempty"`
	TitleStatus      ThreadTitleStatus `json:"title_status,omitempty"`
	TitleSource      ThreadTitleSource `json:"title_source,omitempty"`
	TitleUpdatedAt   time.Time         `json:"title_updated_at,omitempty"`
	TitleError       string            `json:"title_error,omitempty"`
	TitleGeneration  int64             `json:"title_generation,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"`
}

func (ThreadSummary) Validate 

func (s ThreadSummary) Validate() error

Validate checks the complete public transcript-free thread summary contract.

type ThreadTitleEditor 

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

ThreadTitleEditor is title authority for one exact root thread.

func (*ThreadTitleEditor) Set 

func (editor *ThreadTitleEditor) Set(ctx context.Context, title string) (ThreadSnapshot, error)

Set replaces the canonical title of the bound thread.

type ThreadTitleMode 

type ThreadTitleMode string

ThreadTitleMode selects who owns durable thread title generation. 

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

type ThreadTitleSource 

type ThreadTitleSource string

ThreadTitleSource identifies who committed a ready canonical thread title. The zero value is valid while a title is unset, pending, or failed. 

const (
	ThreadTitleSourceUnset    ThreadTitleSource = ""
	ThreadTitleSourceHost     ThreadTitleSource = threadTitleSourceHost
	ThreadTitleSourceProvider ThreadTitleSource = threadTitleSourceProvider
)

func ParseThreadTitleSource 

func ParseThreadTitleSource(raw string) (ThreadTitleSource, error)

ParseThreadTitleSource validates raw public title source text.

func (ThreadTitleSource) Valid 

func (s ThreadTitleSource) Valid() bool

Valid reports whether the source is supported. The zero value represents no committed title source.

type ThreadTitleStatus 

type ThreadTitleStatus string

ThreadTitleStatus is the finite lifecycle state of a canonical thread title. The zero value means that no title generation or host title has been recorded. 

const (
	ThreadTitleStatusUnset   ThreadTitleStatus = ""
	ThreadTitleStatusPending ThreadTitleStatus = threadTitleStatusPending
	ThreadTitleStatusReady   ThreadTitleStatus = threadTitleStatusReady
	ThreadTitleStatusFailed  ThreadTitleStatus = threadTitleStatusFailed
)

func ParseThreadTitleStatus 

func ParseThreadTitleStatus(raw string) (ThreadTitleStatus, error)

ParseThreadTitleStatus validates raw public title status text.

func (ThreadTitleStatus) Valid 

func (s ThreadTitleStatus) Valid() bool

Valid reports whether the status is a supported public title state. The zero value is valid and represents a thread without title state.

type ThreadTurnCursor 

type ThreadTurnCursor string

ThreadTurnCursor is an opaque position in one thread's canonical turn path. Hosts may persist and compare the token, but must not parse or modify it.

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"
	ThreadTurnFailureEffectOutcomeUnknown     ThreadTurnFailureCode = "effect_outcome_unknown"
	ThreadTurnFailureAuthorizationUnavailable ThreadTurnFailureCode = "authorization_unavailable"
	ThreadTurnFailureAuthorizationContract    ThreadTurnFailureCode = "authorization_contract"
	ThreadTurnFailureStorage                  ThreadTurnFailureCode = "storage"
	ThreadTurnFailureEngineContract           ThreadTurnFailureCode = "engine_contract"
	ThreadTurnFailureLegacyUnclassified       ThreadTurnFailureCode = "legacy_unclassified"
)

func (ThreadTurnFailureCode) Valid 

func (c ThreadTurnFailureCode) Valid() bool

type ThreadTurnProjection 

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 

func ProjectThreadTurn(req ProjectThreadTurnRequest) ThreadTurnProjection

func (ThreadTurnProjection) Validate 

func (p ThreadTurnProjection) Validate() error

type ThreadTurnProjectionSegment 

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 

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

type ThreadTurnProjectionSignal 

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 ThreadTurnRetrySource 

type ThreadTurnRetrySource struct {
	// TurnID is the canonical source turn. Its internal journal anchor remains
	// private to Floret.
	TurnID TurnID `json:"turn_id"`
}

type ThreadTurnSnapshot 

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 is the opaque identity of the admitted canonical user Entry.
	// It is a presentation anchor, not authorization or a storage access handle.
	UserEntryID       string                  `json:"user_entry_id,omitempty"`
	UserMessageOrigin ThreadUserMessageOrigin `json:"user_message_origin,omitempty"`
	UserInput         string                  `json:"user_input,omitempty"`
	UserAttachments   []MessageAttachment     `json:"user_attachments,omitempty"`
	UserReferences    []MessageReference      `json:"user_references,omitempty"`
	RetrySource       *ThreadTurnRetrySource  `json:"retry_source,omitempty"`
	Status            TurnStatus              `json:"status"`
	Failure           *ThreadTurnFailure      `json:"failure,omitempty"`
	Recoverable       bool                    `json:"recoverable"`
	CanRetry          bool                    `json:"can_retry"`
	Projection        ThreadTurnProjection    `json:"projection"`
	ControlSignals    []ThreadControlSignal   `json:"control_signals,omitempty"`
	ThroughOrdinal    int64                   `json:"through_ordinal"`
}

func (ThreadTurnSnapshot) Validate 

func (s ThreadTurnSnapshot) Validate() error

Validate checks the self-contained public turn snapshot shape. Durable path and admission authority are validated before this DTO is projected.

type ThreadTurnsPage 

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

func (ThreadTurnsPage) Validate 

func (p ThreadTurnsPage) Validate() error

Validate checks one public turn page without consulting persisted state.

type ThreadTurnsRequest added in v2.1.0 

type ThreadTurnsRequest struct {
	BeforeCursor *ThreadTurnCursor
	SinceCursor  *ThreadTurnCursor
	Tail         int
	Limit        int
}

ThreadTurnsRequest selects a canonical turn page after ThreadID is bound.

type ThreadUserMessageOrigin 

type ThreadUserMessageOrigin string

ThreadUserMessageOrigin identifies how Floret admitted one canonical user message. Hosts may use it for presentation, but it is not authorization or a storage locator. 

const (
	ThreadUserMessageOriginUser                  ThreadUserMessageOrigin = "user"
	ThreadUserMessageOriginDelegatedMission      ThreadUserMessageOrigin = "delegated_mission"
	ThreadUserMessageOriginSubAgentInput         ThreadUserMessageOrigin = "subagent_input"
	ThreadUserMessageOriginPendingToolCompletion ThreadUserMessageOrigin = "pending_tool_completion"
)

type ToolCallStream added in v2.2.0 

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

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

type ToolSurface 

type ToolSurface struct {
	Tools                 *tools.Registry
	ToolDefinitions       []tools.ToolDefinition
	HostedToolDefinitions []publicprovider.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 

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

type ToolSurfaceRequest 

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 

type TraceID string

type TurnCompletionPolicy 

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 

type TurnID 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
}

TurnLimits contains per-run budget and continuation caps.

type TurnProjectionAvailability 

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

func (TurnProjectionAvailability) Valid 

func (a TurnProjectionAvailability) Valid() bool

type TurnRequest 

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

TurnRequest describes one provider execution after ThreadID is bound by a TurnRunner.

type TurnResult 

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"`
	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"`
	ProjectionAvailability TurnProjectionAvailability     `json:"projection_availability"`
	Projection             *ThreadTurnProjection          `json:"projection,omitempty"`
	ProjectionError        string                         `json:"projection_error,omitempty"`
	Replayed               bool                           `json:"replayed,omitempty"`
}

func (TurnResult) Validate 

func (r TurnResult) Validate() error

type TurnRunner 

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

TurnRunner owns provider-backed execution for one exact root thread.

func (*TurnRunner) CompletePendingTool added in v2.1.0 

func (runner *TurnRunner) CompletePendingTool(ctx context.Context, request ActivePendingToolCompletion) (PendingToolCompletionResult, error)

CompletePendingTool admits one host-owned provider continuation on the bound thread.

func (*TurnRunner) ResolveApproval added in v2.1.0 

func (runner *TurnRunner) ResolveApproval(ctx context.Context, request ApprovalResolutionRequest) (ResolveApprovalResult, error)

ResolveApproval submits one decision to the approval queue rooted at the bound thread.

func (*TurnRunner) Retry added in v2.1.0 

func (runner *TurnRunner) Retry(ctx context.Context, request RetryRequest) (TurnResult, error)

Retry retries the latest eligible turn on the bound thread.

func (*TurnRunner) Run 

func (runner *TurnRunner) Run(ctx context.Context, request TurnRequest) (TurnResult, error)

Run admits and executes one turn on the bound thread.

func (*TurnRunner) SettlePendingTool added in v2.1.0 

func (runner *TurnRunner) SettlePendingTool(ctx context.Context, request ActivePendingToolSettlement) (PendingToolSettlementResult, error)

SettlePendingTool records one host-owned pending tool outcome on the bound thread without resuming provider execution.

func (*TurnRunner) UpdateAgentTodos added in v2.1.0 

func (runner *TurnRunner) UpdateAgentTodos(ctx context.Context, request AgentTodoUpdateRequest) (ThreadAgentTodoState, error)

UpdateAgentTodos atomically updates canonical Agent todos on the bound thread.

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    *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 

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 

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 

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
}

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 

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

type WaitSubAgents 

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

WaitSubAgents describes a bounded wait after ParentThreadID is bound.

type WaitSubAgentsRequest 

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

type WaitSubAgentsResult 

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

func (WaitSubAgentsResult) Validate 

func (r WaitSubAgentsResult) Validate() error

Validate checks one public SubAgent wait result.

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.