runtime

package
v3.2.40 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 40 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
)
View Source 
const MaxAgentTodos = 40

MaxAgentTodos is the canonical upper bound for one Agent todo state.

Variables

View Source 
var (
	// ErrMigrationRequired reports an exact legacy schema that runtime.Open
	// refuses to migrate implicitly.
	ErrMigrationRequired = errors.New("floret storage migration required")
	// ErrUnsupportedSchema reports a nonempty schema outside the v3 contract.
	ErrUnsupportedSchema = errors.New("unsupported floret logical schema")
)
View Source 
var (
	// ErrHostClosed reports that Host shutdown has started.
	ErrHostClosed = errors.New("floret host is closed")
	// ErrRevisionUnavailable reports a thread revision outside retained durable history.
	ErrRevisionUnavailable = errors.New("floret thread revision is unavailable")
	// ErrSubscriptionStale reports a subscription that must be recreated from a new snapshot.
	ErrSubscriptionStale = errors.New("floret subscription is stale")
	// ErrThreadNotFound reports that a requested durable thread was not found.
	ErrThreadNotFound = errors.New("floret thread not found")
	// ErrThreadDeleted reports that a requested durable identity is permanently tombstoned.
	ErrThreadDeleted = errors.New("floret thread is deleted")
	// ErrThreadNotActive reports that an active-only capability no longer owns the thread mutation.
	ErrThreadNotActive = errors.New("floret thread is not active")
	// ErrThreadBusy reports that another active turn or mutation currently owns the thread.
	ErrThreadBusy = errors.New("floret thread is busy")
	// ErrTurnNotFound reports that a requested durable turn was not found.
	ErrTurnNotFound = errors.New("floret turn not found")
	// ErrInterruptedTurnNotFound reports that a live exact recovery target has no active turn lease.
	ErrInterruptedTurnNotFound = errors.New("floret interrupted turn not found")
	// ErrRecoveryTargetResolved reports that an exact interrupted-turn target no longer owns its bound lease generation.
	ErrRecoveryTargetResolved = errors.New("floret interrupted turn recovery target is resolved")
	// ErrRunNotFound reports that a requested durable run was not found.
	ErrRunNotFound = errors.New("floret run not found")
	// ErrArtifactNotFound reports that a requested durable artifact was not found.
	ErrArtifactNotFound = errors.New("floret artifact not found")
	// ErrNoRetryTarget reports that a thread has no canonical turn eligible for retry.
	ErrNoRetryTarget = errors.New("floret thread has no retry target")
	// ErrPendingToolNotFound reports that a settlement target does not identify a canonical tool call.
	ErrPendingToolNotFound = errors.New("floret pending tool not found")
	// ErrPendingToolNotActive reports that a settlement target is not an active pending tool result.
	ErrPendingToolNotActive = errors.New("floret pending tool is not active")
	// ErrPendingToolSettlementConflict reports that a pending tool was already settled differently.
	ErrPendingToolSettlementConflict = errors.New("floret pending tool settlement conflict")
	// ErrSubAgentNotFound reports that a requested parent-scoped child thread was not found.
	ErrSubAgentNotFound = errors.New("floret subagent not found")
	// ErrSubAgentClosed reports that a requested child mutation targets a closed SubAgent.
	ErrSubAgentClosed = errors.New("floret subagent is closed")
	// ErrSubAgentClosing reports that an explicit close operation owns the child subtree.
	ErrSubAgentClosing = errors.New("floret subagent is closing")
	// ErrStaleAuthority reports that a local proof no longer owns the durable generation.
	ErrStaleAuthority = errors.New("floret authority proof is stale")
	// ErrRequestConflict reports durable request identity reuse with changed input.
	ErrRequestConflict = errors.New("floret request conflicts with persisted authority")
	// ErrAuthorityCorrupt reports an impossible durable authority shape.
	ErrAuthorityCorrupt = errors.New("floret authority state is corrupt")
	// ErrExecutionPlanUnavailable means an uncommitted admitted turn predates
	// durable execution plans and must first be replayed through the deprecated
	// command-bearing execution API with its exact v3.0 command.
	ErrExecutionPlanUnavailable = errors.New("floret admitted turn execution plan is unavailable")
	// ErrExecutionPlanMismatch means the current Agent cannot execute the
	// immutable plan bound at admission.
	ErrExecutionPlanMismatch = errors.New("floret admitted turn execution plan does not match the Agent")
	// ErrExecutionContextIncomplete means a durable plan requires a process-
	// local implementation, such as a signal projector, that was not supplied.
	ErrExecutionContextIncomplete = errors.New("floret admitted turn execution context is incomplete")
	// ErrUnsupportedStoreCapability reports a backend that lacks required atomicity.
	ErrUnsupportedStoreCapability = errors.New("floret store capability is unsupported")
	// ErrEffectUnauthorized reports a current host-policy denial before handler entry.
	ErrEffectUnauthorized = errors.New("floret effect is unauthorized")
	// ErrAuthorizationUnavailable reports a host-policy, approval, audit, or gate failure before handler entry.
	ErrAuthorizationUnavailable = errors.New("floret effect authorization is unavailable")
	// ErrInvalidAuthorizationProof reports a proof that does not match the canonical invocation.
	ErrInvalidAuthorizationProof = errors.New("floret effect authorization proof is invalid")
	// ErrEffectDispatchConsumed reports reuse or deferred use of a one-shot authorized effect.
	ErrEffectDispatchConsumed = errors.New("floret authorized effect dispatch was consumed")
	// ErrEffectOutcomeUnknown reports an invocation that crossed dispatch without a known result.
	ErrEffectOutcomeUnknown = errors.New("floret effect outcome is unknown")
	// ErrAuthorizationContract reports a host gate that did not return the closure's sealed result.
	ErrAuthorizationContract = errors.New("floret effect authorization contract failed")
	// ErrStoreClosed reports that the store has started closing.
	ErrStoreClosed = ErrHostClosed
	// ErrSubAgentParentRequired reports that a child operation used a root-thread capability.
	ErrSubAgentParentRequired = errors.New("floret subagent operation requires parent authority")
	// ErrForkOperationConflict reports that an operation ID was reused with a different fork request.
	ErrForkOperationConflict = errors.New("floret fork operation conflicts with existing request")
	// ErrForkDestinationConflict reports that a planned destination is owned by another operation or node.
	ErrForkDestinationConflict = errors.New("floret fork destination conflicts with operation plan")
	// ErrAgentTodoVersionConflict reports that a todo update was based on a stale canonical version.
	ErrAgentTodoVersionConflict = errors.New("floret agent todo version conflict")
	// ErrJournalInvariant reports an ambiguous active path that Floret refuses to repair heuristically.
	ErrJournalInvariant = errors.New("floret thread journal invariant violated")
	// ErrThreadAuthorityInvariant reports invalid durable root/SubAgent ownership metadata.
	ErrThreadAuthorityInvariant = errors.New("floret thread authority invariant violated")
)
View Source 
var (
	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 identity.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.

func ValidateAgentTodos added in v3.1.0 

func ValidateAgentTodos(items []AgentTodo) error

ValidateAgentTodos checks the canonical Agent todo collection invariants.

Types

type ActivePendingToolTarget 

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

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

type AdmitTurnResult added in v3.0.3 

type AdmitTurnResult struct {
	ThreadID    identity.ThreadID    `json:"thread_id"`
	TurnID      identity.TurnID      `json:"turn_id"`
	RunID       identity.RunID       `json:"run_id"`
	UserEntryID string               `json:"user_entry_id"`
	Receipt     TurnAdmissionReceipt `json:"receipt"`
	// contains filtered or unexported fields
}

AdmitTurnResult returns a durable admission receipt plus a process-local execution handle. Persist the receipt, not the handle.

func (AdmitTurnResult) Execute added in v3.0.3 

func (result AdmitTurnResult) Execute(ctx context.Context) (StartTurnResult, error)

Execute starts or replays provider execution for this admitted turn.

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 WithAgentManualCompactions added in v3.0.1 

func WithAgentManualCompactions(source ManualCompactionSource) AgentOption

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

func 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 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           identity.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        identity.ThreadID `json:"thread_id"`
	TurnID          identity.TurnID   `json:"turn_id"`
	RunID           identity.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      identity.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           identity.ThreadID  `json:"root_thread_id,omitempty"`
	ParentThreadID         identity.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                  identity.RunID     `json:"run_id,omitempty"`
	ThreadID               identity.ThreadID  `json:"thread_id,omitempty"`
	TurnID                 identity.TurnID    `json:"turn_id,omitempty"`
	Step                   int                `json:"step,omitempty"`
	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 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 ArtifactRef 

type ArtifactRef struct {
	ID        identity.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 AuthoritativeThreadTurnProjection added in v3.1.0 

type AuthoritativeThreadTurnProjection struct {
	Projection ThreadTurnProjection           `json:"projection"`
	Revision   ThreadRevision                 `json:"revision"`
	Provenance ThreadTurnProjectionProvenance `json:"provenance"`
}

AuthoritativeThreadTurnProjection is a canonical projection read from Floret at one exact thread revision.

func (AuthoritativeThreadTurnProjection) Validate added in v3.1.0 

func (projection AuthoritativeThreadTurnProjection) Validate() error

Validate checks one authoritative projection envelope.

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 Child 

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

Child is read authority bound to one direct child of a Thread. It does not inherit root-thread mutation authority.

func (*Child) ID 

func (child *Child) ID() identity.ThreadID

ID returns the direct child identity bound to this read handle.

func (*Child) InterruptedTurnRecovery added in v3.0.2 

func (child *Child) InterruptedTurnRecovery(ctx context.Context) (*InterruptedTurnRecovery, error)

InterruptedTurnRecovery binds the current durable interrupted proof of the bound Child without recovering it yet.

func (*Child) ListPendingToolTargets 

func (child *Child) ListPendingToolTargets(ctx context.Context) ([]PendingToolSettlementTarget, error)

ListPendingToolTargets returns unsettled host-owned work for the direct child bound to this handle.

func (*Child) ListTurns added in v3.0.2 

func (child *Child) ListTurns(ctx context.Context, request ThreadTurnsRequest) (ThreadTurnsPage, error)

ListTurns returns one canonical turn page from the bound direct Child.

func (*Child) PendingToolRecovery added in v3.0.2 

func (child *Child) PendingToolRecovery(ctx context.Context, target PendingToolSettlementTarget) (*PendingToolRecovery, error)

PendingToolRecovery binds provider-free settlement authority for one exact target on the bound Child.

func (*Child) ReadDetail 

func (child *Child) ReadDetail(ctx context.Context, request ThreadDetailRequest) (SubAgentDetail, error)

ReadDetail returns canonical detail for the direct child bound to this handle. The child identity cannot be substituted by the caller.

func (*Child) ReadTurn added in v3.0.2 

func (child *Child) ReadTurn(ctx context.Context, turnID identity.TurnID) (ThreadTurnSnapshot, error)

ReadTurn returns one exact canonical turn from the bound direct Child.

type CloseSubAgentCommand added in v3.0.1 

type CloseSubAgentCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ChildThreadID    identity.ThreadID         `json:"child_thread_id"`
	Reason           string                    `json:"reason"`
}

CloseSubAgentCommand closes one direct child of the bound parent.

type CloseSubAgentResult added in v3.0.1 

type CloseSubAgentResult struct {
	Child   SubAgentSnapshot `json:"child"`
	Receipt MutationReceipt  `json:"receipt"`
}

CloseSubAgentResult reports the canonical child after closure.

type CommittedCleanupError 

type CommittedCleanupError struct {
	ThreadID identity.ThreadID
	Err      error
}

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

func (*CommittedCleanupError) Error 

func (e *CommittedCleanupError) Error() string

func (*CommittedCleanupError) Unwrap 

func (e *CommittedCleanupError) Unwrap() error

type CommittedEffectError 

type CommittedEffectError struct {
	EffectAttemptID string
	Err             error
}

func (*CommittedEffectError) Error 

func (e *CommittedEffectError) Error() string

func (*CommittedEffectError) Unwrap 

func (e *CommittedEffectError) Unwrap() error

type CompactThreadCommand added in v3.0.1 

type CompactThreadCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	Source           string                    `json:"source"`
	Labels           RunLabels                 `json:"labels,omitempty"`
	Limits           TurnLimits                `json:"limits,omitempty"`
	Reasoning        config.ReasoningSelection `json:"reasoning,omitempty"`
}

CompactThreadCommand runs one provider-backed compaction on the bound Thread. LogicalRequestID is also the durable compaction request identity.

type CompactThreadResult added in v3.0.1 

type CompactThreadResult struct {
	ThreadID         identity.ThreadID            `json:"thread_id"`
	RunID            identity.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"`
}

CompactThreadResult is the canonical terminal result of one standalone provider-backed compaction.

func (CompactThreadResult) Validate added in v3.0.1 

func (r CompactThreadResult) Validate() error

Validate checks one public standalone compaction result.

type ContinuePendingToolCommand 

type ContinuePendingToolCommand struct {
	LogicalRequestID identity.LogicalRequestID   `json:"logical_request_id"`
	Target           ActivePendingToolTarget     `json:"target"`
	Status           PendingToolCompletionStatus `json:"status"`
	Summary          string                      `json:"summary,omitempty"`
	Output           string                      `json:"output,omitempty"`
	Input            TurnInput                   `json:"input"`
	Labels           RunLabels                   `json:"labels,omitempty"`
}

ContinuePendingToolCommand settles one active pending tool and resumes the bound thread with Floret-allocated continuation identities.

type ContinuePendingToolResult 

type ContinuePendingToolResult struct {
	Completion PendingToolCompletionResult `json:"completion"`
	Receipt    MutationReceipt             `json:"receipt"`
}

ContinuePendingToolResult reports the canonical continuation and its durable logical-mutation receipt.

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 CreateThreadCommand 

type CreateThreadCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
}

CreateThreadCommand creates a root thread. LogicalRequestID is the only caller-provided identity.

type CreateThreadResult 

type CreateThreadResult struct {
	ThreadID identity.ThreadID `json:"thread_id"`
	Receipt  MutationReceipt   `json:"receipt"`
}

CreateThreadResult returns the Floret-allocated thread identity.

type DeleteThreadCommand 

type DeleteThreadCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
}

DeleteThreadCommand permanently deletes the bound thread lifecycle.

type DeleteThreadResult 

type DeleteThreadResult struct {
	ThreadID identity.ThreadID `json:"thread_id"`
	Receipt  MutationReceipt   `json:"receipt"`
}

DeleteThreadResult reports the durable tombstone revision.

type DeletedEvent 

type DeletedEvent struct {
	ThreadID         identity.ThreadID         `json:"thread_id"`
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	DeletedAt        time.Time                 `json:"deleted_at"`
}

DeletedEvent is the final durable fact for a deleted thread.

type DerivedThreadTurnProjection added in v3.1.0 

type DerivedThreadTurnProjection struct {
	Projection ThreadTurnProjection           `json:"projection"`
	Provenance ThreadTurnProjectionProvenance `json:"provenance"`
}

DerivedThreadTurnProjection is a validated offline calculation. It is not a canonical read and must not be persisted as Floret lifecycle authority.

func DeriveThreadTurn added in v3.1.0 

func DeriveThreadTurn(req ProjectThreadTurnRequest) (DerivedThreadTurnProjection, error)

DeriveThreadTurn validates an offline projection from caller-supplied detail events and labels it as non-authoritative.

func (DerivedThreadTurnProjection) Validate added in v3.1.0 

func (projection DerivedThreadTurnProjection) Validate() error

Validate checks one derived projection without claiming canonical authority.

type DescendantReader 

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

DescendantReader is read authority bound to one validated descendant.

func (*DescendantReader) ID 

func (reader *DescendantReader) ID() identity.ThreadID

ID returns the descendant identity bound to this read handle.

func (*DescendantReader) ListTurns 

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

ListTurns returns one canonical turn page from the descendant bound to this handle.

func (*DescendantReader) ReadArtifact 

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

ReadArtifact returns one artifact owned by the descendant bound to this handle.

func (*DescendantReader) ReadTurn 

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

ReadTurn returns one canonical turn from the descendant bound to this handle.

type DurableThreadEvent 

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

DurableThreadEvent is one sealed revision or deletion variant. Its fields are private so revision and payload cannot disagree.

func (DurableThreadEvent) Change 

func (event DurableThreadEvent) Change() (ThreadRevisionEvent, bool)

Change returns the changed-domain event only for DurableThreadEventRevision.

func (DurableThreadEvent) Deleted 

func (event DurableThreadEvent) Deleted() (DeletedEvent, bool)

Deleted returns the tombstone fact only for DurableThreadEventDeleted.

func (DurableThreadEvent) Kind 

func (event DurableThreadEvent) Kind() DurableThreadEventKind

Kind reports the durable event variant.

func (DurableThreadEvent) MarshalJSON 

func (event DurableThreadEvent) MarshalJSON() ([]byte, error)

MarshalJSON emits one discriminator and exactly one durable payload.

func (DurableThreadEvent) Revision 

func (event DurableThreadEvent) Revision() ThreadRevision

Revision reports the exact thread revision committed by this event.

func (*DurableThreadEvent) UnmarshalJSON 

func (event *DurableThreadEvent) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes one discriminator-selected durable payload.

type DurableThreadEventKind 

type DurableThreadEventKind string

DurableThreadEventKind identifies the one durable event value. The zero value is invalid. 

const (
	DurableThreadEventRevision DurableThreadEventKind = "revision"
	DurableThreadEventDeleted  DurableThreadEventKind = "deleted"
)

type EffectAuthorizationGate 

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

type EffectAuthorizationGateFunc 

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

func (EffectAuthorizationGateFunc) Dispatch 

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

type EffectAuthorizationProof 

type EffectAuthorizationProof struct {
	EffectAttemptID    string            `json:"effect_attempt_id"`
	RequestFingerprint string            `json:"request_fingerprint"`
	ThreadID           identity.ThreadID `json:"thread_id"`
	TurnID             identity.TurnID   `json:"turn_id"`
	RunID              identity.RunID    `json:"run_id"`
	ToolCallID         string            `json:"tool_call_id"`
	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           identity.ThreadID `json:"thread_id"`
	TurnID             identity.TurnID   `json:"turn_id"`
	RunID              identity.RunID    `json:"run_id"`
	ToolCallID         string            `json:"tool_call_id"`
	ToolName           string            `json:"tool_name"`
	ArgumentHash       string            `json:"argument_hash"`
	Step               int               `json:"step"`
	BatchIndex         int               `json:"batch_index"`
	BatchSize          int               `json:"batch_size"`
	Labels             map[string]string `json:"labels,omitempty"`
	HostContext        map[string]string `json:"host_context,omitempty"`
	// Activity is detached tool-authored display data. It is never authority.
	Activity          *tools.ActivityPresentation `json:"activity,omitempty"`
	Resources         []tools.ResourceRef         `json:"resources,omitempty"`
	Effects           []tools.Effect              `json:"effects,omitempty"`
	Permission        tools.PermissionSpec        `json:"permission"`
	ReadOnly          bool                        `json:"read_only"`
	Destructive       bool                        `json:"destructive"`
	OpenWorld         bool                        `json:"open_world"`
	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            identity.TraceID                  `json:"trace_id,omitempty"`
	RunID              identity.RunID                    `json:"run_id,omitempty"`
	ThreadID           identity.ThreadID                 `json:"thread_id,omitempty"`
	TurnID             identity.TurnID                   `json:"turn_id,omitempty"`
	Step               int                               `json:"step,omitempty"`
	Provider           string                            `json:"provider,omitempty"`
	Model              string                            `json:"model,omitempty"`
	Message            string                            `json:"message,omitempty"`
	Result             string                            `json:"result,omitempty"`
	Error              string                            `json:"error,omitempty"`
	ToolID             string                            `json:"tool_id,omitempty"`
	ToolName           string                            `json:"tool_name,omitempty"`
	ToolKind           string                            `json:"tool_kind,omitempty"`
	ArgsHash           string                            `json:"args_hash,omitempty"`
	DurationMS         int64                             `json:"duration_ms,omitempty"`
	FinishReason       observation.FinishReason          `json:"finish_reason,omitempty"`
	RawFinishReason    string                            `json:"raw_finish_reason,omitempty"`
	FinishInferred     bool                              `json:"finish_inferred,omitempty"`
	CompletionReason   observation.CompletionReason      `json:"completion_reason,omitempty"`
	ContinuationReason observation.ContinuationReason    `json:"continuation_reason,omitempty"`
	Activity           *tools.ActivityPresentation       `json:"activity,omitempty"`
	ActivityTimeline   *observation.ActivityTimeline     `json:"activity_timeline,omitempty"`
	Projection         *ThreadTurnProjection             `json:"projection,omitempty"`
	ProjectionDelta    *ThreadTurnProjectionDelta        `json:"projection_delta,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 ExecutionContext added in v3.1.0 

type ExecutionContext struct {
	SupplementalContext []TurnSupplementalContextItem
	SignalProjector     func(tools.ToolCall) (TurnSignal, bool, error)
}

ExecutionContext contains only process-local input needed to execute an already admitted canonical turn. It is never persisted in the journal, request ledger, provider continuation state, or canonical references.

type ForkThreadCommand 

type ForkThreadCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
}

ForkThreadCommand forks the bound thread to a Floret-allocated identity.

type ForkThreadResult added in v3.1.0 

type ForkThreadResult = ForkThreadResultV3

ForkThreadResult returns the Floret-allocated destination identity.

type ForkThreadResultV3 

type ForkThreadResultV3 struct {
	ThreadID identity.ThreadID `json:"thread_id"`
	Receipt  MutationReceipt   `json:"receipt"`
}

ForkThreadResultV3 returns the Floret-allocated destination identity. Deprecated: use ForkThreadResult.

type Host 

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

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

func Open 

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

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

func (*Host) Shutdown 

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

Shutdown stops admission, cancels Host-managed execution, and waits for all owned resources. A timed-out caller may call Shutdown again to keep waiting.

func (*Host) Thread 

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

Thread binds a canonical handle to one existing exact thread.

func (*Host) Threads 

func (host *Host) Threads() *Threads

Threads returns root-thread collection authority.

type IDSource 

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

IDSource supplies Floret-owned execution identities. Deprecated: production hosts must use the cryptographic source installed by Open; tests should use florettest.NewIDSource.

type InterruptSubAgentCommand 

type InterruptSubAgentCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ChildThreadID    identity.ThreadID         `json:"child_thread_id"`
	Input            TurnInput                 `json:"input"`
	Labels           RunLabels                 `json:"labels,omitempty"`
}

InterruptSubAgentCommand admits one canonical interrupting input to a direct child. Interruption is distinct from closing the child lifecycle.

type InterruptSubAgentResult 

type InterruptSubAgentResult struct {
	Child   SubAgentSnapshot `json:"child"`
	Receipt MutationReceipt  `json:"receipt"`
}

InterruptSubAgentResult reports the canonical child after interrupt admission.

type InterruptedTurnRecovery added in v3.0.2 

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

InterruptedTurnRecovery owns the exact durable interrupted-turn proof that was current when the bound Thread or Child issued this handle.

func (*InterruptedTurnRecovery) Recover added in v3.0.2 

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

Recover atomically finalizes the exact interrupted proof bound at issuance.

type InterruptedTurnRecoveryCandidate added in v3.2.13 

type InterruptedTurnRecoveryCandidate struct {
	ThreadID       identity.ThreadID `json:"thread_id"`
	ParentThreadID identity.ThreadID `json:"parent_thread_id,omitempty"`
}

InterruptedTurnRecoveryCandidate identifies one exact root or child thread that has a canonical turn lease requiring host-side recovery inspection. ParentThreadID is empty for roots.

type ListThreadsOptions 

type ListThreadsOptions struct {
	Cursor ThreadListCursor `json:"cursor,omitempty"`
	Limit  int              `json:"limit,omitempty"`
}

ListThreadsOptions selects one bounded root-thread inventory page.

type LoopLimits 

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

type ManualCompactionPollRequest 

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

type ManualCompactionRequest 

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

type ManualCompactionSource 

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

type MessageAttachment 

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

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

func (MessageAttachment) Validate 

func (a MessageAttachment) Validate() error

type MessageAttachmentTextStats 

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

type MessageReference 

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

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

func (MessageReference) Validate 

func (r MessageReference) Validate() error

type MessageReferenceKind 

type MessageReferenceKind string

type MigrationRequiredError 

type MigrationRequiredError struct {
	Version string
}

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

func (*MigrationRequiredError) Error 

func (failure *MigrationRequiredError) Error() string

Error describes the required explicit migration.

func (*MigrationRequiredError) Is 

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

Is classifies MigrationRequiredError with ErrMigrationRequired.

type MutationReceipt 

type MutationReceipt struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ThreadID         identity.ThreadID         `json:"thread_id"`
	TurnID           identity.TurnID           `json:"turn_id,omitempty"`
	RunID            identity.RunID            `json:"run_id,omitempty"`
	Revision         ThreadRevision            `json:"revision"`
	Committed        bool                      `json:"committed"`
	Replayed         bool                      `json:"replayed"`
}

MutationReceipt reports the durable identity and commit position of one logical mutation.

type Options 

type Options struct {
	Storage publicstorage.Source
	// IDSource exists only for v3 source compatibility.
	// Deprecated: production hosts must leave this nil; tests should use
	// florettest.NewIDSource.
	IDSource           IDSource
	SubscriptionBuffer int
}

Options configures one runtime Host.

type PendingToolCompletionResult 

type PendingToolCompletionResult struct {
	CompletionRequestID string            `json:"completion_request_id"`
	ThreadID            identity.ThreadID `json:"thread_id"`
	TurnID              identity.TurnID   `json:"turn_id"`
	RunID               identity.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 added in v3.0.2 

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

PendingToolRecovery is provider-free settlement authority bound to one exact pending tool on one bound Thread or Child.

func (*PendingToolRecovery) Settle added in v3.0.2 

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

Settle records the bound pending tool outcome exactly once or replays it.

type PendingToolRecoveryRequest added in v3.0.2 

type PendingToolRecoveryRequest struct {
	Status   PendingToolSettlementStatus `json:"status"`
	Summary  string                      `json:"summary,omitempty"`
	Output   string                      `json:"output,omitempty"`
	Activity *tools.ActivityPresentation `json:"activity,omitempty"`
}

PendingToolRecoveryRequest records one terminal host-owned outcome without provider execution after exact target authority has been bound.

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        identity.ThreadID `json:"thread_id"`
	TurnID          identity.TurnID   `json:"turn_id"`
	RunID           identity.RunID    `json:"run_id"`
	ToolCallID      string            `json:"tool_call_id"`
	ToolName        string            `json:"tool_name"`
	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 identity.ThreadID
	TurnID   identity.TurnID
	RunID    identity.RunID
	TraceID  identity.TraceID
	Events   []ThreadDetailEvent
}

type RecordPendingToolOutcomeCommand 

type RecordPendingToolOutcomeCommand struct {
	LogicalRequestID identity.LogicalRequestID   `json:"logical_request_id"`
	Target           ActivePendingToolTarget     `json:"target"`
	Status           PendingToolSettlementStatus `json:"status"`
	Summary          string                      `json:"summary,omitempty"`
	Output           string                      `json:"output,omitempty"`
	Activity         *tools.ActivityPresentation `json:"activity,omitempty"`
}

RecordPendingToolOutcomeCommand records a terminal host-owned outcome without starting provider execution.

type RecordPendingToolOutcomeResult 

type RecordPendingToolOutcomeResult struct {
	Outcome PendingToolSettlementResult `json:"outcome"`
	Receipt MutationReceipt             `json:"receipt"`
}

RecordPendingToolOutcomeResult reports the canonical outcome and mutation receipt.

type RecoverInterruptedTurnResult added in v3.0.2 

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

func (RecoverInterruptedTurnResult) Validate added in v3.0.2 

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 ResolveApprovalCommand 

type ResolveApprovalCommand struct {
	LogicalRequestID         identity.LogicalRequestID `json:"logical_request_id"`
	DecisionID               string                    `json:"decision_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"`
}

ResolveApprovalCommand resolves one exact approval authority snapshot.

type ResolveApprovalCommandResult 

type ResolveApprovalCommandResult struct {
	Resolution ResolveApprovalResult `json:"resolution"`
	Receipt    MutationReceipt       `json:"receipt"`
}

ResolveApprovalCommandResult reports the canonical decision and mutation receipt. Deprecated: use ResolveApprovalMutationResult.

type ResolveApprovalMutationResult added in v3.1.0 

type ResolveApprovalMutationResult = ResolveApprovalCommandResult

ResolveApprovalMutationResult reports the canonical decision and mutation receipt using the standard mutation-result naming pattern.

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 RetryTurnCommand 

type RetryTurnCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	Reason           string                    `json:"reason,omitempty"`
	Labels           RunLabels                 `json:"labels,omitempty"`
}

RetryTurnCommand retries the latest eligible canonical turn.

type RetryTurnResult 

type RetryTurnResult struct {
	ThreadID identity.ThreadID `json:"thread_id"`
	TurnID   identity.TurnID   `json:"turn_id"`
	RunID    identity.RunID    `json:"run_id"`
	Receipt  MutationReceipt   `json:"receipt"`
}

RetryTurnResult returns the Floret-allocated retry execution identities.

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 SendSubAgentMessageCommand 

type SendSubAgentMessageCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ChildThreadID    identity.ThreadID         `json:"child_thread_id"`
	Input            TurnInput                 `json:"input"`
	Labels           RunLabels                 `json:"labels,omitempty"`
}

SendSubAgentMessageCommand admits one canonical input to a direct child.

type SendSubAgentMessageResult 

type SendSubAgentMessageResult struct {
	Child   SubAgentSnapshot `json:"child"`
	Receipt MutationReceipt  `json:"receipt"`
}

SendSubAgentMessageResult reports the canonical child after input admission.

type SetThreadTitleCommand added in v3.0.2 

type SetThreadTitleCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	Title            string                    `json:"title"`
}

SetThreadTitleCommand replaces the canonical title of the bound Thread.

type SetThreadTitleResult added in v3.0.2 

type SetThreadTitleResult struct {
	Thread  ThreadSnapshot  `json:"thread"`
	Receipt MutationReceipt `json:"receipt"`
}

SetThreadTitleResult reports the canonical snapshot and durable mutation.

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 SpawnSubAgentCommand 

type SpawnSubAgentCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ParentTurnID     identity.TurnID           `json:"parent_turn_id,omitempty"`
	TaskName         string                    `json:"task_name"`
	TaskDescription  string                    `json:"task_description,omitempty"`
	Input            TurnInput                 `json:"input"`
	HostProfileRef   string                    `json:"host_profile_ref,omitempty"`
	ForkMode         SubAgentForkMode          `json:"fork_mode"`
	Labels           RunLabels                 `json:"labels,omitempty"`
}

SpawnSubAgentCommand creates one direct child below the bound parent. The child ThreadID is allocated by Floret and is never caller supplied.

type SpawnSubAgentResult 

type SpawnSubAgentResult struct {
	Child   SubAgentSnapshot `json:"child"`
	Receipt MutationReceipt  `json:"receipt"`
}

SpawnSubAgentResult reports the canonical child and durable mutation receipt.

type StartTurnCommand 

type StartTurnCommand struct {
	LogicalRequestID    identity.LogicalRequestID     `json:"logical_request_id"`
	UserMessage         TurnInput                     `json:"user_message"`
	SupplementalContext []TurnSupplementalContextItem `json:"supplemental_context,omitempty"`
	Labels              RunLabels                     `json:"labels,omitempty"`
	Completion          TurnCompletionPolicy          `json:"completion,omitempty"`
	Signals             TurnSignalSpec                `json:"signals,omitempty"`
	Limits              TurnLimits                    `json:"limits,omitempty"`
	Reasoning           config.ReasoningSelection     `json:"reasoning,omitempty"`
}

StartTurnCommand admits one canonical user message on a bound Thread.

type StartTurnResult 

type StartTurnResult struct {
	ThreadID         identity.ThreadID     `json:"thread_id"`
	TurnID           identity.TurnID       `json:"turn_id"`
	RunID            identity.RunID        `json:"run_id"`
	Receipt          MutationReceipt       `json:"receipt"`
	AdmissionReceipt *TurnAdmissionReceipt `json:"admission_receipt,omitempty"`
}

StartTurnResult returns the canonical result and Floret-allocated execution identities for one admitted turn.

type StreamObservation 

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

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

func (StreamObservation) Validate 

func (s StreamObservation) Validate() error

type StreamObservationType 

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

func (StreamObservationType) Valid 

func (t StreamObservationType) Valid() bool

type 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 SubAgentForkMode 

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

type SubAgentManager added in v3.1.0 

type SubAgentManager interface {
	List(context.Context) ([]SubAgentSnapshot, error)
	SpawnSubAgent(context.Context, SpawnSubAgentCommand) (SpawnSubAgentResult, error)
	SendSubAgentMessage(context.Context, SendSubAgentMessageCommand) (SendSubAgentMessageResult, error)
	InterruptSubAgent(context.Context, InterruptSubAgentCommand) (InterruptSubAgentResult, error)
	WaitSubAgents(context.Context, WaitSubAgentsCommand) (WaitSubAgentsResult, error)
	CloseSubAgent(context.Context, CloseSubAgentCommand) (CloseSubAgentResult, error)
}

SubAgentManager is direct-child lifecycle authority bound to one exact parent Thread and immutable Agent snapshot.

type SubAgentSnapshot 

type SubAgentSnapshot struct {
	ThreadID        identity.ThreadID `json:"thread_id"`
	Path            string            `json:"path"`
	TaskName        string            `json:"task_name"`
	TaskDescription string            `json:"task_description,omitempty"`
	ParentThreadID  identity.ThreadID `json:"parent_thread_id"`
	ParentTurnID    identity.TurnID   `json:"parent_turn_id,omitempty"`
	HostProfileRef  string            `json:"host_profile_ref,omitempty"`
	ForkMode        SubAgentForkMode  `json:"fork_mode,omitempty"`
	Status          SubAgentStatus    `json:"status"`
	LatestTurnID    identity.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 SubscribeOptions 

type SubscribeOptions struct {
	AfterRevision ThreadRevision `json:"after_revision"`
}

SubscribeOptions starts an exact-thread stream after one snapshot revision.

type Subscription 

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

Subscription is a linearized pull stream for one exact thread.

func (*Subscription) Close 

func (subscription *Subscription) Close() error

Close releases subscription resources. It is idempotent.

func (*Subscription) Next 

func (subscription *Subscription) Next(ctx context.Context) (SubscriptionMessage, error)

Next returns exactly one message. Calls are serialized even when multiple goroutines share the Subscription.

type SubscriptionGap 

type SubscriptionGap struct {
	LastDeliveredRevision ThreadRevision `json:"last_delivered_revision"`
	ResyncAtRevision      ThreadRevision `json:"resync_at_revision"`
}

SubscriptionGap requires a fresh snapshot/query/subscribe handshake.

type SubscriptionMessage 

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

SubscriptionMessage is one sealed durable, transient, or gap variant. Its fields are intentionally private so callers cannot construct an ambiguous combination.

func (SubscriptionMessage) Durable 

func (message SubscriptionMessage) Durable() (DurableThreadEvent, bool)

Durable returns the durable event only for SubscriptionMessageDurable.

func (SubscriptionMessage) Gap 

func (message SubscriptionMessage) Gap() (SubscriptionGap, bool)

Gap returns the resynchronization boundary only for SubscriptionMessageGap.

func (SubscriptionMessage) Kind 

func (message SubscriptionMessage) Kind() SubscriptionMessageKind

Kind reports the message variant.

func (SubscriptionMessage) MarshalJSON 

func (message SubscriptionMessage) MarshalJSON() ([]byte, error)

MarshalJSON emits one discriminator and exactly one variant value.

func (SubscriptionMessage) Transient 

func (message SubscriptionMessage) Transient() (Event, bool)

Transient returns the observation event only for SubscriptionMessageTransient.

func (*SubscriptionMessage) UnmarshalJSON 

func (message *SubscriptionMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes one discriminator-selected variant.

type SubscriptionMessageKind 

type SubscriptionMessageKind string

SubscriptionMessageKind identifies the one value carried by a subscription message. The zero value is invalid. 

const (
	SubscriptionMessageDurable   SubscriptionMessageKind = "durable"
	SubscriptionMessageTransient SubscriptionMessageKind = "transient"
	SubscriptionMessageGap       SubscriptionMessageKind = "gap"
)

type Thread 

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

Thread is canonical authority bound to one exact durable thread.

func (*Thread) Compactor added in v3.1.0 

func (thread *Thread) Compactor(agent *Agent) (ThreadCompactor, error)

Compactor grants provider-backed compaction authority bound to this exact Thread and Agent.

func (*Thread) ID 

func (thread *Thread) ID() identity.ThreadID

ID returns the bound canonical thread identity.

func (*Thread) Lifecycle added in v3.1.0 

func (thread *Thread) Lifecycle() (ThreadLifecycle, error)

Lifecycle grants lifecycle mutation and recovery authority for this exact Thread.

func (*Thread) Reader added in v3.1.0 

func (thread *Thread) Reader() (ThreadReader, error)

Reader grants read-only authority for this exact Thread.

func (*Thread) SubAgentManager added in v3.1.0 

func (thread *Thread) SubAgentManager(ctx context.Context, agent *Agent) (SubAgentManager, error)

SubAgentManager grants direct-child lifecycle authority bound to this exact parent Thread and Agent.

func (*Thread) TurnExecutor added in v3.1.0 

func (thread *Thread) TurnExecutor(agent *Agent) (TurnExecutor, error)

TurnExecutor grants turn authority bound to this exact Thread and Agent.

type ThreadAgentTodoState 

type ThreadAgentTodoState struct {
	ThreadID          identity.ThreadID `json:"thread_id"`
	Version           int64             `json:"version"`
	Items             []AgentTodo       `json:"items"`
	UpdatedAt         time.Time         `json:"updated_at,omitempty"`
	UpdatedByTurnID   identity.TurnID   `json:"updated_by_turn_id,omitempty"`
	UpdatedByRunID    identity.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 ThreadBootstrap added in v3.1.0 

type ThreadBootstrap struct {
	Revision           ThreadRevision                `json:"revision"`
	Thread             ThreadSnapshot                `json:"thread"`
	Overview           ThreadOverview                `json:"overview"`
	Turns              ThreadTurnsPage               `json:"turns"`
	Approvals          ApprovalQueue                 `json:"approvals"`
	AgentTodos         ThreadAgentTodoState          `json:"agent_todos"`
	Context            ThreadContextSnapshot         `json:"context"`
	PendingToolTargets []PendingToolSettlementTarget `json:"pending_tool_targets,omitempty"`
	SubAgents          []SubAgentSnapshot            `json:"subagents,omitempty"`
}

ThreadBootstrap is a complete initial read model observed while the bound Thread remained at one exact revision. Subscribe with AfterRevision equal to Revision to continue without a snapshot/event gap.

func (ThreadBootstrap) Validate added in v3.1.0 

func (bootstrap ThreadBootstrap) Validate() error

Validate checks bootstrap identity and canonical result consistency.

type ThreadBootstrapRequest added in v3.1.0 

type ThreadBootstrapRequest struct {
	TurnLimit int `json:"turn_limit,omitempty"`
}

ThreadBootstrapRequest selects the canonical turn page included in a bootstrap read model.

type ThreadChangeDomain 

type ThreadChangeDomain string

ThreadChangeDomain identifies one canonical read model changed by a durable revision. Consumers re-query that domain at the event revision. 

const (
	ThreadChangeThread        ThreadChangeDomain = "thread"
	ThreadChangeJournal       ThreadChangeDomain = "journal"
	ThreadChangeTodo          ThreadChangeDomain = "todo"
	ThreadChangeApproval      ThreadChangeDomain = "approval"
	ThreadChangeEffect        ThreadChangeDomain = "effect"
	ThreadChangeSubAgent      ThreadChangeDomain = "subagent"
	ThreadChangeCompaction    ThreadChangeDomain = "compaction"
	ThreadChangeArtifact      ThreadChangeDomain = "artifact"
	ThreadChangeProviderState ThreadChangeDomain = "provider_state"
)

type ThreadCompactor added in v3.1.0 

type ThreadCompactor interface {
	Compact(context.Context, CompactThreadCommand) (CompactThreadResult, error)
}

ThreadCompactor is provider-backed compaction authority for one exact Thread and immutable Agent snapshot.

type ThreadContextSnapshot 

type ThreadContextSnapshot struct {
	ThreadID    identity.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"`
	ErrorCode   string         `json:"error_code,omitempty"`
	Text        string         `json:"text,omitempty"`
	ArgsHash    string         `json:"args_hash,omitempty"`
	Payload     map[string]any `json:"payload,omitempty"`
}

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"`
	ErrorCode   string         `json:"error_code,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  identity.ThreadID     `json:"thread_id"`
	TurnID    identity.TurnID       `json:"turn_id,omitempty"`
	RunID     identity.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    *tools.ActivityPresentation `json:"activity,omitempty"`
}

type ThreadDetailRequest 

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 ThreadLifecycle added in v3.1.0 

type ThreadLifecycle interface {
	ID() identity.ThreadID
	SetTitle(context.Context, SetThreadTitleCommand) (SetThreadTitleResult, error)
	Fork(context.Context, ForkThreadCommand) (ForkThreadResult, error)
	Delete(context.Context, DeleteThreadCommand) (DeleteThreadResult, error)
	PendingToolRecovery(context.Context, PendingToolSettlementTarget) (*PendingToolRecovery, error)
	InterruptedTurnRecovery(context.Context) (*InterruptedTurnRecovery, error)
}

ThreadLifecycle is mutation and recovery authority for one exact Thread. Keep it at the application composition root or pass it only to lifecycle coordinators.

type ThreadListCursor 

type ThreadListCursor string

ThreadListCursor is an opaque stable position in the root-thread inventory.

type ThreadListItem 

type ThreadListItem struct {
	Thread     ThreadSnapshot      `json:"thread"`
	LatestTurn *ThreadTurnSnapshot `json:"latest_turn,omitempty"`
	Revision   ThreadRevision      `json:"revision"`
}

ThreadListItem pairs one canonical root snapshot and optional latest turn with its own monotonic revision. All fields come from the same inventory snapshot. Thread revisions are intentionally not conflated into a global inventory revision.

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 added in v3.1.0 

type ThreadReader interface {
	ID() identity.ThreadID
	Snapshot(context.Context) (ThreadView, error)
	Bootstrap(context.Context, ThreadBootstrapRequest) (ThreadBootstrap, error)
	ReadOverview(context.Context) (ThreadOverview, error)
	ReadTurn(context.Context, identity.TurnID) (ThreadTurnSnapshot, error)
	ListTurns(context.Context, ThreadTurnsRequest) (ThreadTurnsPage, error)
	ReadAgentTodos(context.Context) (ThreadAgentTodoState, error)
	ReadContext(context.Context) (ThreadContextSnapshot, error)
	ReadApprovalQueue(context.Context) (ApprovalQueue, error)
	ReadAuthoritativeProjection(context.Context, identity.TurnID, identity.RunID) (AuthoritativeThreadTurnProjection, error)
	ListPendingToolTargets(context.Context) ([]PendingToolSettlementTarget, error)
	ListSubAgents(context.Context) ([]SubAgentSnapshot, error)
	Child(context.Context, identity.ThreadID) (*Child, error)
	Descendant(context.Context, identity.ThreadID) (*DescendantReader, error)
	Subscribe(context.Context, SubscribeOptions) (*Subscription, error)
}

ThreadReader is read-only authority for one exact canonical Thread. Applications should pass this interface to read services instead of *Thread.

type ThreadRevision 

type ThreadRevision int64

ThreadRevision is the monotonic durable revision of one exact thread.

type ThreadRevisionEvent 

type ThreadRevisionEvent struct {
	ThreadID    identity.ThreadID    `json:"thread_id"`
	CommittedAt time.Time            `json:"committed_at"`
	Changes     []ThreadChangeDomain `json:"changes"`
}

ThreadRevisionEvent identifies one committed exact-thread revision without duplicating its queryable lifecycle projection in the event stream.

type ThreadSnapshot 

type ThreadSnapshot struct {
	ID               identity.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     identity.TurnID   `json:"latest_turn_id,omitempty"`
	LatestRunID      identity.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               identity.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     identity.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 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"
	ThreadTurnFailureControlError             ThreadTurnFailureCode = "control_error"
	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       identity.ThreadID             `json:"thread_id"`
	TurnID         identity.TurnID               `json:"turn_id"`
	RunID          identity.RunID                `json:"run_id"`
	TraceID        identity.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 ApplyThreadTurnProjectionDelta added in v3.2.29 

func ApplyThreadTurnProjectionDelta(previous *ThreadTurnProjection, delta ThreadTurnProjectionDelta) (ThreadTurnProjection, error)

ApplyThreadTurnProjectionDelta validates and applies one replacement. A zero base ordinal resets any supplied previous projection from a self-contained checkpoint; a nonzero base requires an exact prior ordinal.

func ProjectThreadTurn 

func ProjectThreadTurn(req ProjectThreadTurnRequest) ThreadTurnProjection

ProjectThreadTurn calculates a projection without validating the caller- supplied events. Deprecated: use DeriveThreadTurn, or ThreadReader.ReadAuthoritativeProjection for canonical application state.

func (ThreadTurnProjection) Validate 

func (p ThreadTurnProjection) Validate() error

type ThreadTurnProjectionDelta added in v3.2.29 

type ThreadTurnProjectionDelta struct {
	ThreadID           identity.ThreadID                   `json:"thread_id"`
	TurnID             identity.TurnID                     `json:"turn_id"`
	RunID              identity.RunID                      `json:"run_id"`
	TraceID            identity.TraceID                    `json:"trace_id,omitempty"`
	BaseThroughOrdinal int64                               `json:"base_through_ordinal"`
	ThroughOrdinal     int64                               `json:"through_ordinal"`
	Status             TurnStatus                          `json:"status"`
	SegmentCount       int                                 `json:"segment_count"`
	Changes            []ThreadTurnProjectionSegmentChange `json:"changes,omitempty"`
	ProjectedAt        time.Time                           `json:"projected_at,omitempty"`
}

ThreadTurnProjectionDelta is one validated replacement over a previously observed turn projection. A zero base ordinal is a self-contained checkpoint that may replace any prior local lineage.

func DiffThreadTurnProjections added in v3.2.29 

func DiffThreadTurnProjections(previous *ThreadTurnProjection, current ThreadTurnProjection) (ThreadTurnProjectionDelta, error)

DiffThreadTurnProjections returns the minimal segment replacement delta from previous to current. A nil previous projection denotes the initial frame.

func (ThreadTurnProjectionDelta) Validate added in v3.2.29 

func (delta ThreadTurnProjectionDelta) Validate() error

Validate checks the standalone shape of one projection delta. Apply also verifies its base identity and ordinal against the previous projection.

type ThreadTurnProjectionProvenance added in v3.1.0 

type ThreadTurnProjectionProvenance string

ThreadTurnProjectionProvenance distinguishes authoritative Floret reads from projections derived offline from caller-supplied detail events. 

const (
	ThreadTurnProjectionAuthoritative ThreadTurnProjectionProvenance = "authoritative"
	ThreadTurnProjectionDerived       ThreadTurnProjectionProvenance = "derived"
)

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 ThreadTurnProjectionSegmentChange added in v3.2.29 

type ThreadTurnProjectionSegmentChange struct {
	Index   int                         `json:"index"`
	Segment ThreadTurnProjectionSegment `json:"segment"`
}

ThreadTurnProjectionSegmentChange replaces one segment at its stable index.

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"`
	ErrorCode   string         `json:"error_code,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 identity.TurnID `json:"turn_id"`
}

type ThreadTurnSnapshot 

type ThreadTurnSnapshot struct {
	TurnID           identity.TurnID           `json:"turn_id"`
	RunID            identity.RunID            `json:"run_id"`
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id,omitempty"`
	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       identity.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 

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 ThreadView 

type ThreadView struct {
	Thread   ThreadSnapshot `json:"thread"`
	Revision ThreadRevision `json:"revision"`
}

ThreadView is a current canonical snapshot and its shared read revision.

type Threads 

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

Threads is root-thread collection authority bound to one Host.

func (*Threads) CreateThread 

func (threads *Threads) CreateThread(ctx context.Context, command CreateThreadCommand) (CreateThreadResult, error)

CreateThread creates or permanently replays one root-thread mutation.

func (*Threads) ListInterruptedTurnRecoveryCandidates added in v3.2.13 

func (threads *Threads) ListInterruptedTurnRecoveryCandidates(ctx context.Context) ([]InterruptedTurnRecoveryCandidate, error)

ListInterruptedTurnRecoveryCandidates discovers recovery targets with one canonical store read. It only returns identities; callers must still bind the exact lease proof through ThreadLifecycle.InterruptedTurnRecovery or Child.InterruptedTurnRecovery before recovering.

func (*Threads) ListThreads 

func (threads *Threads) ListThreads(ctx context.Context, options ListThreadsOptions) (ThreadsPage, error)

ListThreads returns root-thread snapshots and optional latest turns in one Floret call. Each item carries the revision of its exact thread; product ordering and read state remain host-owned.

type ThreadsPage 

type ThreadsPage struct {
	Threads    []ThreadListItem `json:"threads"`
	NextCursor ThreadListCursor `json:"next_cursor,omitempty"`
	HasMore    bool             `json:"has_more,omitempty"`
}

ThreadsPage is one stable, bounded root-thread batch.

type ToolCallStream 

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         identity.RunID
	ThreadID      identity.ThreadID
	TurnID        identity.TurnID
	TraceID       identity.TraceID
	PromptScopeID identity.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 TurnAdmissionReceipt added in v3.0.3 

type TurnAdmissionReceipt struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ThreadID         identity.ThreadID         `json:"thread_id"`
	TurnID           identity.TurnID           `json:"turn_id"`
	RunID            identity.RunID            `json:"run_id"`
	UserEntryID      string                    `json:"user_entry_id"`
	Revision         ThreadRevision            `json:"revision"`
	Replayed         bool                      `json:"replayed,omitempty"`
}

TurnAdmissionReceipt is the durable proof that Floret has admitted the canonical user message before provider execution starts.

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 TurnExecutor added in v3.1.0 

type TurnExecutor interface {
	StartTurn(context.Context, StartTurnCommand) (StartTurnResult, error)
	AdmitTurn(context.Context, StartTurnCommand) (AdmitTurnResult, error)
	ExecuteAdmission(context.Context, TurnAdmissionReceipt, ExecutionContext) (StartTurnResult, error)
	RetryTurn(context.Context, RetryTurnCommand) (RetryTurnResult, error)
	ContinuePendingTool(context.Context, ContinuePendingToolCommand) (ContinuePendingToolResult, error)
	RecordPendingToolOutcome(context.Context, RecordPendingToolOutcomeCommand) (RecordPendingToolOutcomeResult, error)
	ResolveApproval(context.Context, ResolveApprovalCommand) (ResolveApprovalMutationResult, error)
	UpdateTodos(context.Context, UpdateTodosCommand) (UpdateTodosResult, error)
}

TurnExecutor is provider-backed turn authority bound to one exact Thread and immutable Agent snapshot.

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 TurnResult 

type TurnResult struct {
	ThreadID               identity.ThreadID              `json:"thread_id"`
	TurnID                 identity.TurnID                `json:"turn_id"`
	RunID                  identity.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 TurnSignal 

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

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
	Identity    string
	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 UpdateTodosCommand 

type UpdateTodosCommand struct {
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id"`
	ExpectedVersion  int64                     `json:"expected_version"`
	Items            []AgentTodo               `json:"items"`
	TurnID           identity.TurnID           `json:"turn_id"`
	RunID            identity.RunID            `json:"run_id"`
	ToolCallID       string                    `json:"tool_call_id"`
}

UpdateTodosCommand replaces the bound thread's typed Agent todo state.

type UpdateTodosResult 

type UpdateTodosResult struct {
	State   ThreadAgentTodoState `json:"state"`
	Receipt MutationReceipt      `json:"receipt"`
}

UpdateTodosResult reports the canonical todo state and mutation receipt.

type WaitSubAgentsCommand added in v3.0.1 

type WaitSubAgentsCommand struct {
	ChildThreadIDs []identity.ThreadID `json:"child_thread_ids"`
	Timeout        time.Duration       `json:"timeout"`
}

WaitSubAgentsCommand waits for selected direct children of the bound parent.

type WaitSubAgentsResult added in v3.0.1 

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

WaitSubAgentsResult reports the selected canonical child snapshots.

func (WaitSubAgentsResult) Validate added in v3.0.1 

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.