runtime

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

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

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

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

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

Index

Constants

View Source 
const (
	CoreControlAskUser      = tools.ControlAskUser
	CoreControlTaskComplete = tools.ControlTaskComplete
)
View Source 
const (
	MessageReferenceText      MessageReferenceKind = "text"
	MessageReferenceFile      MessageReferenceKind = "file"
	MessageReferenceDirectory MessageReferenceKind = "directory"
	MessageReferenceTerminal  MessageReferenceKind = "terminal"
	MessageReferenceProcess   MessageReferenceKind = "process"

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

Variables

View Source 
var (
	// ErrThreadNotFound reports that a requested durable thread was not found.
	ErrThreadNotFound = errors.New("floret thread not found")
	// ErrThreadDeleted reports that a requested durable identity is permanently tombstoned.
	ErrThreadDeleted = errors.New("floret thread is deleted")
	// ErrThreadNotActive reports that an active-only capability no longer owns the thread mutation.
	ErrThreadNotActive = errors.New("floret thread is not active")
	// ErrThreadBusy reports that another active turn or mutation currently owns the thread.
	ErrThreadBusy = errors.New("floret thread is busy")
	// ErrTurnNotFound reports that a requested durable turn was not found.
	ErrTurnNotFound = errors.New("floret turn not found")
	// ErrInterruptedTurnNotFound reports that a live exact recovery target has no active turn lease.
	ErrInterruptedTurnNotFound = errors.New("floret interrupted turn not found")
	// ErrRecoveryTargetResolved reports that an exact interrupted-turn target no longer owns its bound lease generation.
	ErrRecoveryTargetResolved = errors.New("floret interrupted turn recovery target is resolved")
	// ErrRunNotFound reports that a requested durable run was not found.
	ErrRunNotFound = errors.New("floret run not found")
	// ErrArtifactNotFound reports that a requested durable artifact was not found.
	ErrArtifactNotFound = errors.New("floret artifact not found")
	// ErrNoRetryTarget reports that a thread has no canonical turn eligible for retry.
	ErrNoRetryTarget = errors.New("floret thread has no retry target")
	// ErrPendingToolNotFound reports that a settlement target does not identify a canonical tool call.
	ErrPendingToolNotFound = errors.New("floret pending tool not found")
	// ErrPendingToolNotActive reports that a settlement target is not an active pending tool result.
	ErrPendingToolNotActive = errors.New("floret pending tool is not active")
	// ErrPendingToolSettlementConflict reports that a pending tool was already settled differently.
	ErrPendingToolSettlementConflict = errors.New("floret pending tool settlement conflict")
	// ErrSubAgentNotFound reports that a requested parent-scoped child thread was not found.
	ErrSubAgentNotFound = errors.New("floret subagent not found")
	// ErrSubAgentClosed reports that a requested child mutation targets a closed SubAgent.
	ErrSubAgentClosed = errors.New("floret subagent is closed")
	// ErrSubAgentClosing reports that an explicit close operation owns the child subtree.
	ErrSubAgentClosing = errors.New("floret subagent is closing")
	// ErrStaleAuthority reports that a local proof no longer owns the durable generation.
	ErrStaleAuthority = errors.New("floret authority proof is stale")
	// ErrRequestConflict reports durable request identity reuse with changed input.
	ErrRequestConflict = errors.New("floret request conflicts with persisted authority")
	// ErrAuthorityCorrupt reports an impossible durable authority shape.
	ErrAuthorityCorrupt = errors.New("floret authority state is corrupt")
	// ErrUnsupportedStoreCapability reports a backend that lacks required atomicity.
	ErrUnsupportedStoreCapability = errors.New("floret store capability is unsupported")
	// ErrEffectUnauthorized reports a current host-policy denial before handler entry.
	ErrEffectUnauthorized = errors.New("floret effect is unauthorized")
	// ErrAuthorizationUnavailable reports a host-policy, approval, audit, or gate failure before handler entry.
	ErrAuthorizationUnavailable = errors.New("floret effect authorization is unavailable")
	// ErrInvalidAuthorizationProof reports a proof that does not match the canonical invocation.
	ErrInvalidAuthorizationProof = errors.New("floret effect authorization proof is invalid")
	// ErrEffectDispatchConsumed reports reuse or deferred use of a one-shot authorized effect.
	ErrEffectDispatchConsumed = errors.New("floret authorized effect dispatch was consumed")
	// ErrEffectOutcomeUnknown reports an invocation that crossed dispatch without a known result.
	ErrEffectOutcomeUnknown = errors.New("floret effect outcome is unknown")
	// ErrAuthorizationContract reports a host gate that did not return the closure's sealed result.
	ErrAuthorizationContract = errors.New("floret effect authorization contract failed")
	// ErrStoreClosed reports that the Store has started closing.
	ErrStoreClosed = errors.New("floret store is closed")
	// ErrSubAgentParentRequired reports that a child operation used a root-thread capability.
	ErrSubAgentParentRequired = errors.New("floret subagent operation requires parent authority")
	// ErrForkOperationConflict reports that an operation ID was reused with a different fork request.
	ErrForkOperationConflict = errors.New("floret fork operation conflicts with existing request")
	// ErrForkDestinationConflict reports that a planned destination is owned by another operation or node.
	ErrForkDestinationConflict = errors.New("floret fork destination conflicts with operation plan")
	// ErrAgentTodoVersionConflict reports that a todo update was based on a stale canonical version.
	ErrAgentTodoVersionConflict = errors.New("floret agent todo version conflict")
	// ErrJournalInvariant reports an ambiguous active path that Floret refuses to repair heuristically.
	ErrJournalInvariant = errors.New("floret thread journal invariant violated")
	// ErrThreadAuthorityInvariant reports invalid durable root/SubAgent ownership metadata.
	ErrThreadAuthorityInvariant = errors.New("floret thread authority invariant violated")
)
View Source 
var (
	ErrInvalidThreadTurnCursor = errors.New("floret thread turn cursor is invalid")
	ErrStaleThreadTurnCursor   = errors.New("floret thread turn cursor is stale")
)
View Source 
var ErrInvalidThreadInventoryCursor = errors.New("floret thread inventory cursor is invalid")

Functions

func ConfigureHostCapabilities added in v0.18.0 

func ConfigureHostCapabilities(store *Store, configure func(*HostBootstrap) error) (err error)

ConfigureHostCapabilities exposes one short-lived bootstrap scope. The Store rejects a second configuration attempt. Callers may retain only narrow binders created during configure; those binders become active after configure succeeds.

func CoreControlDefinitions added in v0.3.10 

func CoreControlDefinitions(includeTaskComplete bool) []tools.ToolDefinition

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

func ManualCompactionOperationID added in v0.3.33 

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

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

func ProviderSafeCoreControlText added in v0.3.10 

func ProviderSafeCoreControlText(signal TurnSignal) string

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

Types

type AgentTodo added in v0.11.0 

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

type AgentTodoStatus added in v0.11.0 

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

func (AgentTodoStatus) Valid added in v0.11.0 

func (s AgentTodoStatus) Valid() bool

type ApprovalDecision added in v0.20.0 

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

type ApprovalDecisionReceipt added in v0.20.0 

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

func (ApprovalDecisionReceipt) Validate added in v0.20.0 

func (r ApprovalDecisionReceipt) Validate() error

type ApprovalIdentity added in v0.20.0 

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

func (ApprovalIdentity) Validate added in v0.20.0 

func (i ApprovalIdentity) Validate() error

type ApprovalQueue added in v0.20.0 

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

func (ApprovalQueue) Validate added in v0.20.0 

func (q ApprovalQueue) Validate() error

type ApprovalRecord added in v0.20.0 

type ApprovalRecord struct {
	ApprovalID             string             `json:"approval_id,omitempty"`
	RootThreadID           ThreadID           `json:"root_thread_id,omitempty"`
	ParentThreadID         ThreadID           `json:"parent_thread_id,omitempty"`
	ToolCallID             string             `json:"tool_call_id,omitempty"`
	EffectAttemptID        string             `json:"effect_attempt_id,omitempty"`
	ToolName               string             `json:"tool_name,omitempty"`
	ToolKind               string             `json:"tool_kind,omitempty"`
	RunID                  RunID              `json:"run_id,omitempty"`
	ThreadID               ThreadID           `json:"thread_id,omitempty"`
	TurnID                 TurnID             `json:"turn_id,omitempty"`
	Step                   int                `json:"step,omitempty"`
	BatchIndex             int                `json:"batch_index"`
	BatchSize              int                `json:"batch_size"`
	State                  string             `json:"state,omitempty"`
	Revision               int64              `json:"revision,omitempty"`
	QueueSequence          int64              `json:"queue_sequence,omitempty"`
	DecisionID             string             `json:"decision_id,omitempty"`
	RequestedAt            time.Time          `json:"requested_at,omitempty"`
	UpdatedAt              time.Time          `json:"updated_at,omitempty"`
	ResolvedAt             time.Time          `json:"resolved_at,omitempty"`
	ArgsHash               string             `json:"args_hash,omitempty"`
	RequestFingerprint     string             `json:"request_fingerprint,omitempty"`
	AuthorizationProofHash string             `json:"authorization_proof_hash,omitempty"`
	Resources              []ApprovalResource `json:"resources,omitempty"`
	Effects                []string           `json:"effects,omitempty"`
	Labels                 map[string]string  `json:"labels,omitempty"`
	HostContext            map[string]string  `json:"host_context,omitempty"`
	ReadOnly               bool               `json:"read_only,omitempty"`
	Destructive            bool               `json:"destructive,omitempty"`
	OpenWorld              bool               `json:"open_world,omitempty"`
	Reason                 string             `json:"reason,omitempty"`
}

func (ApprovalRecord) Validate added in v0.20.0 

func (p ApprovalRecord) Validate() error

type ApprovalResource added in v0.20.0 

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

func (ApprovalResource) Validate added in v0.20.0 

func (r ApprovalResource) Validate() error

type ArtifactContent added in v0.18.0 

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

func (ArtifactContent) Validate added in v1.0.0 

func (c ArtifactContent) Validate() error

Validate checks one public artifact content result.

type ArtifactID added in v0.18.0 

type ArtifactID string

type ArtifactRef added in v0.3.21 

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

func (ArtifactRef) Validate added in v1.0.0 

func (r ArtifactRef) Validate() error

Validate checks one public artifact reference.

type AuthorityBusyError added in v0.18.0 

type AuthorityBusyError struct {
	Kind AuthorityBusyKind
	Err  error
}

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

func (*AuthorityBusyError) Error added in v0.18.0 

func (e *AuthorityBusyError) Error() string

func (*AuthorityBusyError) Is added in v0.18.0 

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

func (*AuthorityBusyError) Unwrap added in v0.18.0 

func (e *AuthorityBusyError) Unwrap() error

type AuthorityBusyKind added in v0.18.0 

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

type AuthorizedEffect added in v0.18.0 

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 CloseSubAgentRequest added in v0.3.17 

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

type CommittedCleanupError added in v0.18.0 

type CommittedCleanupError struct {
	ThreadID ThreadID
	Err      error
}

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

func (*CommittedCleanupError) Error added in v0.18.0 

func (e *CommittedCleanupError) Error() string

func (*CommittedCleanupError) Unwrap added in v0.18.0 

func (e *CommittedCleanupError) Unwrap() error

type CommittedEffectError added in v0.18.0 

type CommittedEffectError struct {
	EffectAttemptID string
	Err             error
}

func (*CommittedEffectError) Error added in v0.18.0 

func (e *CommittedEffectError) Error() string

func (*CommittedEffectError) Unwrap added in v0.18.0 

func (e *CommittedEffectError) Unwrap() error

type CompactThreadRequest added in v0.3.37 

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

type CompactThreadResult added in v0.3.37 

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

func (CompactThreadResult) Validate added in v0.10.0 

func (r CompactThreadResult) Validate() error

type ContractError added in v1.0.0 

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 added in v1.0.0 

func (e *ContractError) Error() string

func (*ContractError) Is added in v1.0.0 

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

func (*ContractError) Unwrap added in v1.0.0 

func (e *ContractError) Unwrap() error

type CreateIntentID added in v0.18.0 

type CreateIntentID string

type CreateThreadRequest added in v0.13.0 

type CreateThreadRequest struct {
	ThreadID       ThreadID
	CreateIntentID CreateIntentID
}

func (CreateThreadRequest) Validate added in v0.28.0 

func (r CreateThreadRequest) Validate() error

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

type EffectAuthorizationGate added in v0.18.0 

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

type EffectAuthorizationGateFunc added in v0.18.0 

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

func (EffectAuthorizationGateFunc) Dispatch added in v0.18.0 

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

type EffectAuthorizationProof added in v0.18.0 

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

type EffectAuthorizationRequest added in v0.18.0 

type EffectAuthorizationRequest struct {
	EffectAttemptID    string               `json:"effect_attempt_id"`
	RequestFingerprint string               `json:"request_fingerprint"`
	ThreadID           ThreadID             `json:"thread_id"`
	TurnID             TurnID               `json:"turn_id"`
	RunID              RunID                `json:"run_id"`
	ToolCallID         string               `json:"tool_call_id"`
	ToolName           string               `json:"tool_name"`
	ArgumentHash       string               `json:"argument_hash"`
	Step               int                  `json:"step"`
	BatchIndex         int                  `json:"batch_index"`
	BatchSize          int                  `json:"batch_size"`
	Labels             map[string]string    `json:"labels,omitempty"`
	HostContext        map[string]string    `json:"host_context,omitempty"`
	Resources          []tools.ResourceRef  `json:"resources,omitempty"`
	Effects            []tools.Effect       `json:"effects,omitempty"`
	Permission         tools.PermissionSpec `json:"permission"`
	ReadOnly           bool                 `json:"read_only"`
	Destructive        bool                 `json:"destructive"`
	OpenWorld          bool                 `json:"open_world"`
	LeaseOwnerID       string               `json:"lease_owner_id"`
	LeaseGeneration    int64                `json:"lease_generation"`
	ObservedHeartbeat  int64                `json:"observed_heartbeat"`
}

type EffectDispatchResult added in v0.18.0 

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

type Event added in v0.3.0 

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

func (Event) Validate added in v0.5.0 

func (e Event) Validate() error

type EventSink added in v0.3.0 

type EventSink interface {
	EmitEvent(Event)
}

type ForkOperationID added in v0.5.0 

type ForkOperationID string

type ForkThreadRequest added in v0.3.86 

type ForkThreadRequest struct {
	OperationID         ForkOperationID
	SourceThreadID      ThreadID
	DestinationThreadID ThreadID
}

type ForkThreadResult added in v0.3.86 

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

func (ForkThreadResult) Validate added in v1.0.0 

func (r ForkThreadResult) Validate() error

Validate checks one public fork result.

type HostBootstrap added in v0.17.0 

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

HostBootstrap is an active, one-time composition scope for one opened Store. ConfigureHostCapabilities seals it before returning to the caller.

type HostedToolDefinition added in v0.3.40 

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

type InterruptedTurnRecoveryHost added in v0.18.0 

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

InterruptedTurnRecoveryHost finalizes one exact expired turn authority proof.

func (*InterruptedTurnRecoveryHost) RecoverInterruptedTurn added in v0.18.0 

func (h *InterruptedTurnRecoveryHost) RecoverInterruptedTurn(ctx context.Context) (RecoverInterruptedTurnResult, error)

RecoverInterruptedTurn atomically takes over and finalizes the exact proof bound at host construction.

type InterruptedTurnRecoveryHostBinder added in v0.18.0 

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

InterruptedTurnRecoveryHostBinder issues only exact interrupted-turn recovery factories.

func NewInterruptedTurnRecoveryHostBinder added in v0.18.0 

func NewInterruptedTurnRecoveryHostBinder(bootstrap *HostBootstrap) (*InterruptedTurnRecoveryHostBinder, error)

NewInterruptedTurnRecoveryHostBinder constructs the interrupted-turn recovery issuer.

func (*InterruptedTurnRecoveryHostBinder) BindSubAgent added in v0.19.0 

func (b *InterruptedTurnRecoveryHostBinder) BindSubAgent(ctx context.Context, parentThreadID, childThreadID ThreadID) (*InterruptedTurnRecoveryHostFactory, error)

BindSubAgent binds recovery to the exact current turn owner and generation of one child under one parent.

func (*InterruptedTurnRecoveryHostBinder) BindThread added in v0.19.0 

func (b *InterruptedTurnRecoveryHostBinder) BindThread(ctx context.Context, threadID ThreadID) (*InterruptedTurnRecoveryHostFactory, error)

BindThread binds recovery to the exact current turn owner and generation of one root thread.

type InterruptedTurnRecoveryHostFactory added in v0.19.0 

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

InterruptedTurnRecoveryHostFactory refreshes recovery authority for one exact root or parent-child turn owner and generation.

func (*InterruptedTurnRecoveryHostFactory) NewHost added in v0.19.0 

func (f *InterruptedTurnRecoveryHostFactory) NewHost(ctx context.Context, sink EventSink) (*InterruptedTurnRecoveryHost, error)

NewHost binds one recovery attempt to the current complete proof for the factory's exact target.

type ListRootThreadsRequest added in v0.29.0 

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

type ListSubAgentActivityTimelineRequest added in v0.3.44 

type ListSubAgentActivityTimelineRequest struct {
	ParentThreadID ThreadID
	Meta           observation.ActivityRunMeta
}

type ListSubAgentPendingToolSettlementTargetsRequest added in v0.28.0 

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

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

type ListThreadDetailEventsRequest added in v0.3.42 

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

type ListThreadTurnsRequest added in v0.11.0 

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

type LoopLimits added in v0.3.0 

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

type ManualCompactionPollRequest added in v0.3.27 

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

type ManualCompactionRequest added in v0.3.27 

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

type ManualCompactionSource added in v0.3.27 

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

type MessageAttachment added in v0.12.0 

type MessageAttachment struct {
	ResourceRef string                      `json:"resource_ref"`
	Name        string                      `json:"name"`
	MIMEType    string                      `json:"mime_type"`
	SizeBytes   int64                       `json:"size_bytes,omitempty"`
	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 added in v0.12.0 

func (a MessageAttachment) Validate() error

type MessageAttachmentTextStats added in v0.25.0 

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

type MessageReference added in v0.20.0 

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 added in v0.20.0 

func (r MessageReference) Validate() error

type MessageReferenceKind added in v0.20.0 

type MessageReferenceKind string

type ModelEvent added in v0.3.1 

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

ModelEvent carries streamed model output.

type ModelEventType added in v0.3.1 

type ModelEventType string

ModelEventType is a streamed model event kind. 

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

type ModelGateway added in v0.3.1 

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

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

type ModelGatewayAttachmentPayloadMode added in v0.25.0 

type ModelGatewayAttachmentPayloadMode string
const (
	ModelGatewayAttachmentPayloadDescriptors ModelGatewayAttachmentPayloadMode = ""
	ModelGatewayAttachmentPayloadExpanded    ModelGatewayAttachmentPayloadMode = "expanded"
)

type ModelGatewayCapabilities added in v0.23.0 

type ModelGatewayCapabilities struct {
	Reasoning         *config.ReasoningCapability
	AttachmentPayload ModelGatewayAttachmentPayloadMode
}

ModelGatewayCapabilities describes host-resolved behavior for a gateway model. A nil Reasoning means the host did not resolve the capability; an explicit Kind="none" value means the host resolved that reasoning is unsupported.

type ModelGatewayIdentity added in v0.3.71 

type ModelGatewayIdentity struct {
	Provider              string
	Model                 string
	StateCompatibilityKey string
}

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

type ModelGatewayRequestPreparer added in v0.25.0 

type ModelGatewayRequestPreparer interface {
	PrepareModelRequest(context.Context, ModelRequest) (PreparedModelRequest, error)
}

ModelGatewayRequestPreparer optionally renders one complete model request before Floret applies context pressure and request limits.

type ModelMessage added in v0.3.1 

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

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

func (ModelMessage) Validate added in v0.10.0 

func (m ModelMessage) Validate() error

type ModelMessageRole added in v0.10.0 

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

func (ModelMessageRole) Valid added in v0.10.0 

func (r ModelMessageRole) Valid() bool

type ModelRequest added in v0.3.1 

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

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

type ModelRequestTokenEstimate added in v0.25.0 

type ModelRequestTokenEstimate struct {
	PrefixTokens         int64
	MessageTokens        int64
	ToolDefinitionTokens int64
	EstimatedInputTokens int64
	Source               string
	Method               string
	Confidence           string
	Coverage             ModelRequestTokenEstimateCoverage
}

ModelRequestTokenEstimate covers the complete rendered request, including host-expanded attachment payloads.

type ModelRequestTokenEstimateCoverage added in v0.25.0 

type ModelRequestTokenEstimateCoverage string
const ModelRequestTokenEstimateCoverageComplete ModelRequestTokenEstimateCoverage = "complete_request"

type ModelState added in v0.3.1 

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

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

type ModelToolCallStream added in v0.3.16 

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

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

type ModelToolResult added in v0.10.0 

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

type PendingToolCompletionRequest added in v0.3.10 

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

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

type PendingToolCompletionResult added in v0.18.0 

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

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

func (PendingToolCompletionResult) Validate added in v0.18.0 

func (r PendingToolCompletionResult) Validate() error

type PendingToolCompletionStatus added in v0.3.10 

type PendingToolCompletionStatus string

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

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

type PendingToolRecoveryHost added in v0.18.0 

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

PendingToolRecoveryHost settles host-owned pending tool work when no active provider owner exists for the bound thread or parent.

func (*PendingToolRecoveryHost) SettlePendingTool added in v0.18.0 

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

type PendingToolRecoveryHostBinder added in v0.18.0 

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

PendingToolRecoveryHostBinder issues only provider-free recovery settlement handles.

func NewPendingToolRecoveryHostBinder added in v0.18.0 

func NewPendingToolRecoveryHostBinder(bootstrap *HostBootstrap) (*PendingToolRecoveryHostBinder, error)

NewPendingToolRecoveryHostBinder constructs the recovery settlement issuer.

func (*PendingToolRecoveryHostBinder) NewSubAgentHost added in v0.18.0 

func (b *PendingToolRecoveryHostBinder) NewSubAgentHost(ctx context.Context, parentThreadID ThreadID, sink EventSink) (*PendingToolRecoveryHost, error)

NewSubAgentHost constructs recovery settlement authority for one SubAgent parent.

func (*PendingToolRecoveryHostBinder) NewThreadHost added in v0.18.0 

func (b *PendingToolRecoveryHostBinder) NewThreadHost(ctx context.Context, threadID ThreadID, sink EventSink) (*PendingToolRecoveryHost, error)

NewThreadHost constructs recovery settlement authority for one root thread.

type PendingToolSettlementRequest added in v0.3.54 

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

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

type PendingToolSettlementResult added in v0.3.54 

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

func (PendingToolSettlementResult) Validate added in v0.10.0 

func (r PendingToolSettlementResult) Validate() error

type PendingToolSettlementStatus added in v0.3.54 

type PendingToolSettlementStatus string

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

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

type PendingToolSettlementTarget added in v0.9.0 

type PendingToolSettlementTarget struct {
	ThreadID        ThreadID `json:"thread_id"`
	TurnID          TurnID   `json:"turn_id"`
	RunID           RunID    `json:"run_id"`
	ToolCallID      string   `json:"tool_call_id"`
	ToolName        string   `json:"tool_name"`
	Handle          string   `json:"handle"`
	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 added in v1.0.0 

func (t PendingToolSettlementTarget) Validate() error

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

type PreparedModelRequest added in v0.25.0 

type PreparedModelRequest interface {
	StreamModel(context.Context) (<-chan ModelEvent, error)
	TokenEstimate() ModelRequestTokenEstimate
	RenderedPayloadFingerprint() string
	Close() error
}

PreparedModelRequest is an immutable, single-use rendering of one exact ModelRequest. StreamModel consumes it; Close discards or releases it and must be idempotent. Prepared handles are in-memory only.

type ProjectThreadTurnRequest added in v0.3.49 

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

type PromptScopeID added in v0.3.0 

type PromptScopeID string

type ProviderUsage added in v0.3.1 

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

ProviderUsage is normalized provider token and cost usage.

type PublishSubAgentPendingToolCompletionRequest added in v0.18.0 

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

type ReadApprovalQueueRequest added in v0.20.0 

type ReadApprovalQueueRequest struct {
	ThreadID ThreadID
}

type ReadArtifactRequest added in v0.18.0 

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

type ReadSubAgentDetailRequest added in v0.3.21 

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

type ReadThreadTurnRequest added in v0.31.0 

type ReadThreadTurnRequest struct {
	ThreadID ThreadID
	TurnID   TurnID
}

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

type ReadTurnProjectionRequest added in v0.3.69 

type ReadTurnProjectionRequest struct {
	ThreadID ThreadID
	TurnID   TurnID
	RunID    RunID
}

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

type RecoverInterruptedTurnResult added in v0.18.0 

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

func (RecoverInterruptedTurnResult) Validate added in v1.0.0 

func (r RecoverInterruptedTurnResult) Validate() error

Validate checks one public interrupted-turn recovery result.

type RequestConflictError added in v0.18.0 

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 added in v0.18.0 

func (e *RequestConflictError) Error() string

func (*RequestConflictError) Is added in v0.18.0 

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

func (*RequestConflictError) Unwrap added in v0.18.0 

func (e *RequestConflictError) Unwrap() error

type ResolveApprovalRequest added in v0.20.0 

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

func (ResolveApprovalRequest) Validate added in v0.20.0 

func (r ResolveApprovalRequest) Validate() error

type ResolveApprovalResult added in v0.20.0 

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

func (ResolveApprovalResult) Validate added in v0.20.0 

func (r ResolveApprovalResult) Validate() error

type RetryTurnRequest added in v0.3.0 

type RetryTurnRequest struct {
	ThreadID ThreadID
	Reason   string
	Labels   RunLabels
}

type RootThreadsPage added in v0.29.0 

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

func (RootThreadsPage) Validate added in v0.29.0 

func (p RootThreadsPage) Validate() error

type RunID added in v0.3.0 

type RunID string

type RunLabels added in v0.3.0 

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

type RunMetrics added in v0.3.1 

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

RunMetrics summarizes the observable work completed by a run.

type RunTurnRequest added in v0.3.0 

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

func (RunTurnRequest) Validate added in v0.28.0 

func (r RunTurnRequest) Validate() error

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

type SQLiteMigrationPolicy added in v0.28.0 

type SQLiteMigrationPolicy string

SQLiteMigrationPolicy controls whether StartSQLiteStore may apply a compatible schema migration. The zero value refuses migration. 

const (
	SQLiteMigrationRefuse          SQLiteMigrationPolicy = "refuse"
	SQLiteMigrationApplyCompatible SQLiteMigrationPolicy = "apply_compatible"
)

type SQLiteStartupPhase added in v0.28.0 

type SQLiteStartupPhase string
const (
	SQLiteStartupInspecting SQLiteStartupPhase = "inspecting"
	SQLiteStartupMigrating  SQLiteStartupPhase = "migrating"
	SQLiteStartupVerifying  SQLiteStartupPhase = "verifying"
	SQLiteStartupOpening    SQLiteStartupPhase = "opening"
)

type SQLiteStartupProgress added in v0.28.0 

type SQLiteStartupProgress struct {
	Phase       SQLiteStartupPhase              `json:"phase"`
	Maintenance *SQLiteStoreMaintenanceProgress `json:"maintenance,omitempty"`
}

SQLiteStartupProgress reports the current startup phase. Maintenance is set only for detailed migration progress; ordinary hosts can observe Phase alone.

type SQLiteStartupRequest added in v0.28.0 

type SQLiteStartupRequest struct {
	MigrationPolicy SQLiteMigrationPolicy
	// MigrationOperationID is an optional correlation ID for an applied
	// migration. StartSQLiteStore derives a stable ID when it is omitted.
	MigrationOperationID string
	Progress             func(SQLiteStartupProgress)
}

SQLiteStartupRequest configures one inspected and exact Store open. Existing current or migrated stores are also verified before open; missing or empty stores are initialized under the inspected precondition.

type SQLiteStartupResult added in v0.28.0 

type SQLiteStartupResult struct {
	Store        *Store
	Inspection   *SQLiteStoreInspection
	Verification *SQLiteStoreVerification
	Migration    *SQLiteStoreMigrationResult
}

SQLiteStartupResult preserves the maintenance facts completed before a Store was opened or startup failed. Store is non-nil only on success.

func StartSQLiteStore added in v0.28.0 

func StartSQLiteStore(ctx context.Context, path string, request SQLiteStartupRequest, options ...SQLiteStoreOption) (SQLiteStartupResult, error)

StartSQLiteStore runs the safe maintenance state machine and returns an exact-open Store. It never migrates unless apply_compatible is explicit.

func (SQLiteStartupResult) Validate added in v1.0.0 

func (r SQLiteStartupResult) Validate() error

Validate checks the maintenance facts carried by one Store startup result.

type SQLiteStoreAction added in v0.26.0 

type SQLiteStoreAction string
const (
	SQLiteStoreActionRetryInspection     SQLiteStoreAction = "retry_inspection"
	SQLiteStoreActionMigrate             SQLiteStoreAction = "migrate"
	SQLiteStoreActionRequiresNewerReader SQLiteStoreAction = "requires_newer_reader"
	SQLiteStoreActionExportDiagnostics   SQLiteStoreAction = "export_diagnostics"
)

type SQLiteStoreInspection added in v0.26.0 

type SQLiteStoreInspection struct {
	Kind                 SQLiteStoreKind              `json:"kind"`
	State                SQLiteStoreState             `json:"state"`
	Exists               bool                         `json:"exists"`
	Empty                bool                         `json:"empty"`
	Observed             StoreSchemaIdentity          `json:"observed"`
	Current              StoreSchemaIdentity          `json:"current"`
	Migratable           []StoreSchemaMigrationSource `json:"migratable"`
	PersistedLeasePolicy *StoreLeasePolicy            `json:"persisted_lease_policy,omitempty"`
	RequestedLeasePolicy StoreLeasePolicy             `json:"requested_lease_policy"`
	LeasePolicyState     SQLiteStoreLeasePolicyState  `json:"lease_policy_state"`
	AutomaticMigration   bool                         `json:"automatic_migration"`
	RequiresExclusive    bool                         `json:"requires_exclusive_access"`
	Retryable            bool                         `json:"retryable"`
	SafeToRetry          bool                         `json:"safe_to_retry"`
	Actions              []SQLiteStoreAction          `json:"actions,omitempty"`
	Reason               SQLiteStoreReason            `json:"reason"`
	SafeDetail           string                       `json:"safe_detail,omitempty"`
}

func InspectSQLiteStore added in v0.26.0 

func InspectSQLiteStore(ctx context.Context, path string, options ...SQLiteStoreOption) (SQLiteStoreInspection, error)

func (SQLiteStoreInspection) Validate added in v1.0.0 

func (i SQLiteStoreInspection) Validate() error

Validate checks one self-contained Store inspection contract.

type SQLiteStoreKind added in v0.26.0 

type SQLiteStoreKind string
const (
	SQLiteStoreKindUnknown SQLiteStoreKind = "unknown"
	SQLiteStoreKindFloret  SQLiteStoreKind = "floret"
)

type SQLiteStoreLeasePolicyState added in v0.26.0 

type SQLiteStoreLeasePolicyState string
const (
	SQLiteStoreLeasePolicyUnavailable SQLiteStoreLeasePolicyState = "unavailable"
	SQLiteStoreLeasePolicyMatches     SQLiteStoreLeasePolicyState = "matches"
	SQLiteStoreLeasePolicyMismatch    SQLiteStoreLeasePolicyState = "mismatch"
)

type SQLiteStoreMaintenanceError added in v0.26.0 

type SQLiteStoreMaintenanceError struct {
	Operation   SQLiteStoreMaintenanceOperation
	Reason      SQLiteStoreReason
	Retryable   bool
	SafeToRetry bool
	Err         error
}

func (*SQLiteStoreMaintenanceError) Error added in v0.26.0 

func (e *SQLiteStoreMaintenanceError) Error() string

func (*SQLiteStoreMaintenanceError) Unwrap added in v0.26.0 

func (e *SQLiteStoreMaintenanceError) Unwrap() error

type SQLiteStoreMaintenanceOperation added in v0.26.0 

type SQLiteStoreMaintenanceOperation string
const (
	SQLiteStoreOperationInspect SQLiteStoreMaintenanceOperation = "inspect"
	SQLiteStoreOperationVerify  SQLiteStoreMaintenanceOperation = "verify"
	SQLiteStoreOperationMigrate SQLiteStoreMaintenanceOperation = "migrate"
	SQLiteStoreOperationOpen    SQLiteStoreMaintenanceOperation = "open"
)

type SQLiteStoreMaintenancePhase added in v0.26.0 

type SQLiteStoreMaintenancePhase string
const (
	SQLiteStoreMaintenancePreflight SQLiteStoreMaintenancePhase = "preflight"
	SQLiteStoreMaintenanceWaiting   SQLiteStoreMaintenancePhase = "waiting_for_exclusive_access"
	SQLiteStoreMaintenanceMigrating SQLiteStoreMaintenancePhase = "migrating"
	SQLiteStoreMaintenanceVerifying SQLiteStoreMaintenancePhase = "verifying"
)

type SQLiteStoreMaintenanceProgress added in v0.26.0 

type SQLiteStoreMaintenanceProgress struct {
	OperationID  string                       `json:"operation_id"`
	Sequence     uint64                       `json:"sequence"`
	Phase        SQLiteStoreMaintenancePhase  `json:"phase"`
	Status       SQLiteStoreMaintenanceStatus `json:"status"`
	Step         int                          `json:"step,omitempty"`
	Total        int                          `json:"total,omitempty"`
	SafeToCancel bool                         `json:"safe_to_cancel"`
	Committed    bool                         `json:"committed"`
	RolledBack   bool                         `json:"rolled_back"`
	Retryable    bool                         `json:"retryable"`
	SafeToRetry  bool                         `json:"safe_to_retry"`
	Reason       SQLiteStoreReason            `json:"reason,omitempty"`
}

type SQLiteStoreMaintenanceStatus added in v0.26.0 

type SQLiteStoreMaintenanceStatus string
const (
	SQLiteStoreMaintenanceRunning   SQLiteStoreMaintenanceStatus = "running"
	SQLiteStoreMaintenanceReady     SQLiteStoreMaintenanceStatus = "ready"
	SQLiteStoreMaintenanceFailed    SQLiteStoreMaintenanceStatus = "failed"
	SQLiteStoreMaintenanceCancelled SQLiteStoreMaintenanceStatus = "cancelled"
)

type SQLiteStoreMigrationMode added in v0.26.0 

type SQLiteStoreMigrationMode string
const (
	SQLiteStoreMigrationPlan  SQLiteStoreMigrationMode = "plan"
	SQLiteStoreMigrationApply SQLiteStoreMigrationMode = "apply"
)

type SQLiteStoreMigrationRequest added in v0.26.0 

type SQLiteStoreMigrationRequest struct {
	OperationID    string
	Mode           SQLiteStoreMigrationMode
	ExpectedSchema StoreSchemaIdentity
	Progress       func(SQLiteStoreMaintenanceProgress)
}

type SQLiteStoreMigrationResult added in v0.26.0 

type SQLiteStoreMigrationResult struct {
	OperationID string                       `json:"operation_id"`
	Mode        SQLiteStoreMigrationMode     `json:"mode"`
	Before      SQLiteStoreInspection        `json:"before"`
	After       SQLiteStoreInspection        `json:"after"`
	Steps       []SQLiteStoreMigrationStep   `json:"steps,omitempty"`
	Status      SQLiteStoreMaintenanceStatus `json:"status"`
	Changed     bool                         `json:"changed"`
	Committed   bool                         `json:"committed"`
	RolledBack  bool                         `json:"rolled_back"`
	Retryable   bool                         `json:"retryable"`
	SafeToRetry bool                         `json:"safe_to_retry"`
	Reason      SQLiteStoreReason            `json:"reason,omitempty"`
}

func MigrateSQLiteStore added in v0.26.0 

func MigrateSQLiteStore(ctx context.Context, path string, request SQLiteStoreMigrationRequest, options ...SQLiteStoreOption) (SQLiteStoreMigrationResult, error)

func (SQLiteStoreMigrationResult) Validate added in v1.0.0 

func (r SQLiteStoreMigrationResult) Validate() error

Validate checks one self-contained Store migration result.

type SQLiteStoreMigrationStep added in v0.26.0 

type SQLiteStoreMigrationStep struct {
	From StoreSchemaIdentity `json:"from"`
	To   StoreSchemaIdentity `json:"to"`
	Code string              `json:"code"`
}

type SQLiteStoreOpenRequest added in v0.27.0 

type SQLiteStoreOpenRequest struct {
	ExpectedState  SQLiteStoreState    `json:"expected_state"`
	ExpectedSchema StoreSchemaIdentity `json:"expected_schema"`
}

SQLiteStoreOpenRequest binds a Store open to a maintenance inspection. Only missing, empty, and current inspections are valid open preconditions.

type SQLiteStoreOption added in v0.26.0 

type SQLiteStoreOption func(*sqliteStoreOptions)

func WithSQLiteStoreLeasePolicy added in v0.26.0 

func WithSQLiteStoreLeasePolicy(policy StoreLeasePolicy) SQLiteStoreOption

type SQLiteStoreReason added in v0.26.0 

type SQLiteStoreReason string
const (
	SQLiteStoreReasonInvalidRequest     SQLiteStoreReason = "invalid_request"
	SQLiteStoreReasonCancelled          SQLiteStoreReason = "cancelled"
	SQLiteStoreReasonBusy               SQLiteStoreReason = "busy"
	SQLiteStoreReasonPermission         SQLiteStoreReason = "permission_denied"
	SQLiteStoreReasonIO                 SQLiteStoreReason = "io_error"
	SQLiteStoreReasonCorrupt            SQLiteStoreReason = "corrupt"
	SQLiteStoreReasonInspectionStale    SQLiteStoreReason = "inspection_stale"
	SQLiteStoreReasonStoreMissing       SQLiteStoreReason = "store_missing"
	SQLiteStoreReasonStoreEmpty         SQLiteStoreReason = "store_empty"
	SQLiteStoreReasonUnrecognized       SQLiteStoreReason = "unrecognized_store"
	SQLiteStoreReasonSchemaMetadata     SQLiteStoreReason = "schema_metadata_invalid"
	SQLiteStoreReasonNewerReader        SQLiteStoreReason = "requires_newer_reader"
	SQLiteStoreReasonUnsupported        SQLiteStoreReason = "unsupported_older_schema"
	SQLiteStoreReasonFingerprint        SQLiteStoreReason = "schema_fingerprint_mismatch"
	SQLiteStoreReasonContract           SQLiteStoreReason = "schema_contract_mismatch"
	SQLiteStoreReasonLegacyMigration    SQLiteStoreReason = "non_empty_schema_requires_legacy_migration"
	SQLiteStoreReasonMigrationAvailable SQLiteStoreReason = "migration_available"
	SQLiteStoreReasonLeaseMismatch      SQLiteStoreReason = "lease_policy_mismatch"
	SQLiteStoreReasonCurrent            SQLiteStoreReason = "store_current"
	SQLiteStoreReasonMigrationFailed    SQLiteStoreReason = "migration_failed"
)

type SQLiteStoreState added in v0.26.0 

type SQLiteStoreState string
const (
	SQLiteStoreStateMissing          SQLiteStoreState = "missing"
	SQLiteStoreStateEmpty            SQLiteStoreState = "empty"
	SQLiteStoreStateCurrent          SQLiteStoreState = "current"
	SQLiteStoreStateUpgradeable      SQLiteStoreState = "upgradeable"
	SQLiteStoreStateUnsupportedOlder SQLiteStoreState = "unsupported_older"
	SQLiteStoreStateFuture           SQLiteStoreState = "future"
	SQLiteStoreStateDrifted          SQLiteStoreState = "drifted"
	SQLiteStoreStateCorrupt          SQLiteStoreState = "corrupt"
	SQLiteStoreStateBusy             SQLiteStoreState = "busy"
	SQLiteStoreStatePermissionDenied SQLiteStoreState = "permission_denied"
	SQLiteStoreStateIOError          SQLiteStoreState = "io_error"
)

type SQLiteStoreVerification added in v0.26.0 

type SQLiteStoreVerification struct {
	Inspection SQLiteStoreInspection          `json:"inspection"`
	Checks     []SQLiteStoreVerificationCheck `json:"checks"`
}

func VerifySQLiteStore added in v0.26.0 

func VerifySQLiteStore(ctx context.Context, path string, options ...SQLiteStoreOption) (SQLiteStoreVerification, error)

func (SQLiteStoreVerification) Validate added in v1.0.0 

func (v SQLiteStoreVerification) Validate() error

Validate checks one self-contained Store verification contract.

type SQLiteStoreVerificationCheck added in v0.26.0 

type SQLiteStoreVerificationCheck struct {
	Code       string `json:"code"`
	Passed     bool   `json:"passed"`
	SafeDetail string `json:"safe_detail,omitempty"`
}

type SendSubAgentInputRequest added in v0.3.17 

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

type SetThreadTitleRequest added in v0.12.0 

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

type SignalDisposition added in v0.3.1 

type SignalDisposition string

SignalDisposition describes how a projected turn signal affects the run. 

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

type SourceRef added in v0.3.13 

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

type SpawnSubAgentRequest added in v0.3.17 

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

type Store added in v0.3.0 

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

func NewMemoryStore added in v0.3.0 

func NewMemoryStore() *Store

func OpenSQLiteStore added in v0.3.0 

func OpenSQLiteStore(ctx context.Context, path string, request SQLiteStoreOpenRequest, options ...SQLiteStoreOption) (*Store, error)

OpenSQLiteStore opens or creates a Store only when its live state still matches a prior maintenance inspection. It never performs an implicit schema migration.

func (*Store) Close added in v0.3.0 

func (s *Store) Close() error

type StoreLeasePolicy added in v0.18.0 

type StoreLeasePolicy struct {
	TTL                time.Duration `json:"ttl"`
	RenewInterval      time.Duration `json:"renew_interval"`
	ClockSkewAllowance time.Duration `json:"clock_skew_allowance"`
}

func (StoreLeasePolicy) Validate added in v0.26.0 

func (p StoreLeasePolicy) Validate() error

type StoreSchemaIdentity added in v0.26.0 

type StoreSchemaIdentity struct {
	Version     string `json:"version"`
	Fingerprint string `json:"fingerprint"`
}

type StoreSchemaMigrationRequirement added in v0.26.0 

type StoreSchemaMigrationRequirement string
const (
	StoreSchemaMigrationRequirementNone               StoreSchemaMigrationRequirement = "none"
	StoreSchemaMigrationRequirementQuiescentAuthority StoreSchemaMigrationRequirement = "quiescent_authority"
)

type StoreSchemaMigrationSource added in v0.26.0 

type StoreSchemaMigrationSource struct {
	Identity    StoreSchemaIdentity             `json:"identity"`
	Requirement StoreSchemaMigrationRequirement `json:"requirement"`
}

type StreamObservation added in v0.3.10 

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

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

func (StreamObservation) Validate added in v0.7.0 

func (s StreamObservation) Validate() error

type StreamObservationType added in v0.3.10 

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

func (StreamObservationType) Valid added in v0.7.0 

func (t StreamObservationType) Valid() bool

type SubAgentActivityTimelineResult added in v0.3.44 

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

func (SubAgentActivityTimelineResult) Validate added in v1.0.0 

func (r SubAgentActivityTimelineResult) Validate() error

Validate checks one public SubAgent activity projection.

type SubAgentDetail added in v0.3.21 

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

func (SubAgentDetail) Validate added in v1.0.0 

func (d SubAgentDetail) Validate() error

Validate checks one public SubAgent detail page.

type SubAgentForkMode added in v0.3.17 

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

type SubAgentHost added in v0.17.0 

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

SubAgentHost owns provider-backed child-thread lifecycle under one canonical parent. Child reads use a separately parent-bound SubAgentReadHost.

func (*SubAgentHost) CloseSubAgent added in v0.17.0 

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

func (*SubAgentHost) PublishPendingToolCompletion added in v0.18.0 

func (h *SubAgentHost) PublishPendingToolCompletion(ctx context.Context, req PublishSubAgentPendingToolCompletionRequest) (SubAgentSnapshot, error)

func (*SubAgentHost) SendSubAgentInput added in v0.17.0 

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

func (*SubAgentHost) SettlePendingTool added in v0.18.0 

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

func (*SubAgentHost) SpawnSubAgent added in v0.17.0 

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

func (*SubAgentHost) WaitSubAgents added in v0.17.0 

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

type SubAgentHostBinder added in v0.18.0 

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

SubAgentHostBinder issues only parent-bound interactive child factories.

func NewSubAgentHostBinder added in v0.18.0 

func NewSubAgentHostBinder(bootstrap *HostBootstrap) (*SubAgentHostBinder, error)

NewSubAgentHostBinder constructs the interactive child issuer.

func (*SubAgentHostBinder) Bind added in v0.18.0 

func (b *SubAgentHostBinder) Bind(parentThreadID ThreadID) (*SubAgentHostFactory, error)

Bind constructs provider-backed child capability factory for exactly one parent.

type SubAgentHostFactory added in v0.17.0 

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

SubAgentHostFactory issues parent-bound interactive child capabilities.

func (*SubAgentHostFactory) NewHost added in v0.17.0 

func (f *SubAgentHostFactory) NewHost(ctx context.Context, opts SubAgentHostOptions) (*SubAgentHost, error)

NewHost constructs a provider-backed child lifecycle capability for one existing parent.

type SubAgentHostOptions added in v0.17.0 

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

SubAgentHostOptions configures one parent-bound interactive child capability.

func NewSubAgentHostOptions added in v1.0.0 

func NewSubAgentHostOptions(cfg config.Config, options ...SubAgentOption) (SubAgentHostOptions, error)

NewSubAgentHostOptions constructs validated options for a parent-bound SubAgent host.

type SubAgentOption added in v1.0.0 

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

SubAgentOption configures one parent-bound SubAgent host.

func WithSubAgentCapabilities added in v1.0.0 

func WithSubAgentCapabilities(capabilities CapabilityOptions) SubAgentOption

WithSubAgentCapabilities configures product-neutral runtime capability sources.

func WithSubAgentDynamicToolSurface added in v1.0.0 

func WithSubAgentDynamicToolSurface(provider ToolSurfaceProvider) SubAgentOption

WithSubAgentDynamicToolSurface configures the per-step tool surface owner.

func WithSubAgentEffectfulTools added in v1.0.0 

func WithSubAgentEffectfulTools(registry *tools.Registry, gate EffectAuthorizationGate) SubAgentOption

WithSubAgentEffectfulTools configures the explicit effect authorization path.

func WithSubAgentEventSink added in v1.0.0 

func WithSubAgentEventSink(sink EventSink) SubAgentOption

WithSubAgentEventSink observes the runtime event contract.

func WithSubAgentIDGenerator added in v1.0.0 

func WithSubAgentIDGenerator(generator func(string) string) SubAgentOption

WithSubAgentIDGenerator supplies deterministic correlation identifiers. It does not derive ThreadID, TurnID, RunID, or PromptScopeID.

func WithSubAgentLoopLimits added in v1.0.0 

func WithSubAgentLoopLimits(limits LoopLimits) SubAgentOption

WithSubAgentLoopLimits configures provider loop limits.

func WithSubAgentModelGateway added in v1.0.0 

func WithSubAgentModelGateway(gateway ModelGateway, identity ModelGatewayIdentity, capabilities ModelGatewayCapabilities) SubAgentOption

WithSubAgentModelGateway atomically configures a custom gateway and its declared identity and capabilities.

func WithSubAgentReadOnlyTools added in v1.0.0 

func WithSubAgentReadOnlyTools(items ...tools.Tool) SubAgentOption

WithSubAgentReadOnlyTools configures an immutable registry snapshot after proving every tool is locally read-only and statically allowed.

func WithSubAgentRunTimeout added in v1.0.0 

func WithSubAgentRunTimeout(timeout time.Duration) SubAgentOption

WithSubAgentRunTimeout bounds one child run without changing its identity.

func WithSubAgentThreadTitleMode added in v1.0.0 

func WithSubAgentThreadTitleMode(mode ThreadTitleMode) SubAgentOption

WithSubAgentThreadTitleMode selects host-owned or provider-owned child titles.

type SubAgentReadHost added in v0.17.0 

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

SubAgentReadHost reads child lifecycle and detail under one bound parent.

func (*SubAgentReadHost) ListPendingToolSettlementTargets added in v0.28.0 

func (h *SubAgentReadHost) ListPendingToolSettlementTargets(ctx context.Context, req ListSubAgentPendingToolSettlementTargetsRequest) ([]PendingToolSettlementTarget, error)

ListPendingToolSettlementTargets returns all canonical active pending tool targets for one direct child under the bound parent. The result is complete and unpaginated.

func (*SubAgentReadHost) ListSubAgentActivityTimeline added in v0.17.0 

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

func (*SubAgentReadHost) ListSubAgents added in v0.17.0 

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

func (*SubAgentReadHost) ListThreadTurns added in v0.29.0 

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

ListThreadTurns returns canonical typed turns for one complete descendant of the parent bound to this read host.

func (*SubAgentReadHost) ReadArtifact added in v0.18.0 

func (h *SubAgentReadHost) ReadArtifact(ctx context.Context, req ReadArtifactRequest) (ArtifactContent, error)

ReadArtifact reads one artifact owned by any complete descendant of the parent thread bound to this capability.

func (*SubAgentReadHost) ReadSubAgentDetail added in v0.17.0 

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

func (*SubAgentReadHost) ReadThreadTurn added in v0.31.0 

func (h *SubAgentReadHost) ReadThreadTurn(ctx context.Context, req ReadThreadTurnRequest) (ThreadTurnSnapshot, error)

ReadThreadTurn returns one canonical turn for a complete descendant of the parent bound to this read host.

type SubAgentReadHostBinder added in v0.18.0 

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

SubAgentReadHostBinder issues only parent-bound child read handles.

func NewSubAgentReadHostBinder added in v0.18.0 

func NewSubAgentReadHostBinder(bootstrap *HostBootstrap) (*SubAgentReadHostBinder, error)

NewSubAgentReadHostBinder constructs the parent-bound child read issuer.

func (*SubAgentReadHostBinder) NewHost added in v0.18.0 

func (b *SubAgentReadHostBinder) NewHost(ctx context.Context, parentThreadID ThreadID) (*SubAgentReadHost, error)

NewHost constructs child reads for exactly one parent.

type SubAgentSnapshot added in v0.3.17 

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

func (SubAgentSnapshot) Validate added in v1.0.0 

func (s SubAgentSnapshot) Validate() error

Validate checks one self-contained public SubAgent projection.

type SubAgentStatus added in v0.3.17 

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

type ThreadAgentTodoState added in v0.11.0 

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

func (ThreadAgentTodoState) Validate added in v1.0.0 

func (s ThreadAgentTodoState) Validate() error

Validate checks one canonical Agent todo projection.

type ThreadCompactionHost added in v0.17.0 

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

ThreadCompactionHost owns provider-backed compaction for one canonical thread.

func (*ThreadCompactionHost) CompactThread added in v0.17.0 

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

type ThreadCompactionHostBinder added in v0.18.0 

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

ThreadCompactionHostBinder issues only thread-bound compaction factories.

func NewThreadCompactionHostBinder added in v0.18.0 

func NewThreadCompactionHostBinder(bootstrap *HostBootstrap) (*ThreadCompactionHostBinder, error)

NewThreadCompactionHostBinder constructs the compaction issuer.

func (*ThreadCompactionHostBinder) Bind added in v0.18.0 

func (b *ThreadCompactionHostBinder) Bind(threadID ThreadID) (*ThreadCompactionHostFactory, error)

Bind constructs provider-backed compaction factory for exactly one root thread.

type ThreadCompactionHostFactory added in v0.17.0 

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

ThreadCompactionHostFactory issues thread-bound compaction capabilities.

func (*ThreadCompactionHostFactory) NewHost added in v0.17.0 

func (f *ThreadCompactionHostFactory) NewHost(ctx context.Context, opts ThreadCompactionHostOptions) (*ThreadCompactionHost, error)

NewHost constructs a provider-backed compaction capability for one existing root thread.

type ThreadCompactionHostOptions added in v0.17.0 

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

ThreadCompactionHostOptions configures one thread-bound compaction capability.

func NewThreadCompactionHostOptions added in v1.0.0 

func NewThreadCompactionHostOptions(cfg config.Config, options ...ThreadCompactionOption) (ThreadCompactionHostOptions, error)

NewThreadCompactionHostOptions constructs validated options for a compaction host.

type ThreadCompactionOption added in v1.0.0 

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

ThreadCompactionOption configures one thread compaction host.

func WithThreadCompactionEventSink added in v1.0.0 

func WithThreadCompactionEventSink(sink EventSink) ThreadCompactionOption

WithThreadCompactionEventSink observes the runtime event contract.

func WithThreadCompactionIDGenerator added in v1.0.0 

func WithThreadCompactionIDGenerator(generator func(string) string) ThreadCompactionOption

WithThreadCompactionIDGenerator supplies deterministic correlation identifiers. It does not derive ThreadID, TurnID, RunID, or PromptScopeID.

func WithThreadCompactionLoopLimits added in v1.0.0 

func WithThreadCompactionLoopLimits(limits LoopLimits) ThreadCompactionOption

WithThreadCompactionLoopLimits configures provider loop limits.

func WithThreadCompactionModelGateway added in v1.0.0 

func WithThreadCompactionModelGateway(gateway ModelGateway, identity ModelGatewayIdentity, capabilities ModelGatewayCapabilities) ThreadCompactionOption

WithThreadCompactionModelGateway atomically configures a custom gateway and its declared identity and capabilities.

type ThreadContextSnapshot added in v0.10.0 

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

func (ThreadContextSnapshot) Validate added in v0.10.0 

func (s ThreadContextSnapshot) Validate() error

type ThreadControlSignal added in v0.11.0 

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

type ThreadCreateHost added in v0.15.0 

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

ThreadCreateHost is the coordinator capability that creates a canonical thread.

func (*ThreadCreateHost) CreateThread added in v0.15.0 

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

type ThreadCreateHostBinder added in v0.18.0 

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

ThreadCreateHostBinder issues only canonical root-thread create handles.

func NewThreadCreateHostBinder added in v0.18.0 

func NewThreadCreateHostBinder(bootstrap *HostBootstrap) (*ThreadCreateHostBinder, error)

NewThreadCreateHostBinder constructs the canonical root-thread create issuer.

func (*ThreadCreateHostBinder) Bind added in v0.18.0 

func (b *ThreadCreateHostBinder) Bind(threadID ThreadID, createIntentID CreateIntentID) (*ThreadCreateHost, error)

Bind constructs canonical root-create authority for one exact identity and durable create intent before it is delivered to a coordinator.

type ThreadDeleteHost added in v0.15.0 

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

ThreadDeleteHost deletes one bound canonical root thread tree.

func (*ThreadDeleteHost) DeleteThread added in v0.15.0 

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

type ThreadDeleteHostBinder added in v0.18.0 

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

ThreadDeleteHostBinder issues only root-thread delete handles.

func NewThreadDeleteHostBinder added in v0.18.0 

func NewThreadDeleteHostBinder(bootstrap *HostBootstrap) (*ThreadDeleteHostBinder, error)

NewThreadDeleteHostBinder constructs the root-thread delete issuer.

func (*ThreadDeleteHostBinder) NewHost added in v0.18.0 

func (b *ThreadDeleteHostBinder) NewHost(ctx context.Context, threadID ThreadID) (*ThreadDeleteHost, error)

NewHost constructs delete authority for exactly one root thread.

type ThreadDetailApproval added in v0.3.42 

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

type ThreadDetailCompaction added in v0.3.42 

type ThreadDetailCompaction struct {
	OperationID         string            `json:"operation_id,omitempty"`
	RequestID           string            `json:"request_id,omitempty"`
	Source              string            `json:"source,omitempty"`
	Trigger             string            `json:"trigger,omitempty"`
	Reason              string            `json:"reason,omitempty"`
	Phase               string            `json:"phase,omitempty"`
	TokensBefore        int64             `json:"tokens_before,omitempty"`
	TokensAfterEstimate int64             `json:"tokens_after_estimate,omitempty"`
	Metadata            map[string]string `json:"metadata,omitempty"`
}

type ThreadDetailControlSignal added in v0.11.0 

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

type ThreadDetailEvent added in v0.3.42 

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

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

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

type ThreadDetailEventKind added in v0.3.42 

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

type ThreadDetailEvents added in v0.3.42 

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

func (ThreadDetailEvents) Validate added in v1.0.0 

func (p ThreadDetailEvents) Validate() error

Validate checks one public detail-event page.

type ThreadDetailMessage added in v0.3.42 

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

type ThreadDetailToolCall added in v0.3.42 

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

type ThreadDetailToolResult added in v0.3.42 

type ThreadDetailToolResult struct {
	CallID          string       `json:"call_id,omitempty"`
	ToolName        string       `json:"tool_name,omitempty"`
	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 added in v0.3.42 

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

type ThreadForkHost added in v0.15.0 

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

ThreadForkHost forks one bound canonical root thread.

func (*ThreadForkHost) ForkThread added in v0.15.0 

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

type ThreadForkHostBinder added in v0.18.0 

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

ThreadForkHostBinder issues only root-thread fork handles.

func NewThreadForkHostBinder added in v0.18.0 

func NewThreadForkHostBinder(bootstrap *HostBootstrap) (*ThreadForkHostBinder, error)

NewThreadForkHostBinder constructs the root-thread fork issuer.

func (*ThreadForkHostBinder) NewHost added in v0.18.0 

func (b *ThreadForkHostBinder) NewHost(ctx context.Context, threadID ThreadID, sink EventSink) (*ThreadForkHost, error)

NewHost constructs fork authority for exactly one source root thread.

type ThreadID added in v0.3.0 

type ThreadID string

type ThreadInventoryCursor added in v0.29.0 

type ThreadInventoryCursor string

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

type ThreadInventoryHost added in v0.29.0 

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

ThreadInventoryHost lists canonical root threads for composition and maintenance coordinators. It is not reachable from a normal run.

func NewThreadInventoryHost added in v0.29.0 

func NewThreadInventoryHost(bootstrap *HostBootstrap) (*ThreadInventoryHost, error)

NewThreadInventoryHost constructs the store-wide canonical root inventory capability for a composition owner.

func (*ThreadInventoryHost) ListRootThreads added in v0.29.0 

func (h *ThreadInventoryHost) ListRootThreads(ctx context.Context, req ListRootThreadsRequest) (RootThreadsPage, error)

ListRootThreads returns one stable page of canonical root threads, including archived roots. Product visibility and ordering remain host-owned concerns.

type ThreadOverview added in v0.12.0 

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

func (ThreadOverview) Validate added in v0.31.0 

func (o ThreadOverview) Validate() error

Validate checks the self-contained public overview shape.

type ThreadPhase added in v0.3.0 

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

func (ThreadPhase) Valid added in v0.29.0 

func (p ThreadPhase) Valid() bool

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

type ThreadReadHost added in v0.15.0 

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

ThreadReadHost reads one bound top-level canonical thread without mutation.

func (*ThreadReadHost) ListPendingToolSettlementTargets added in v0.28.0 

func (h *ThreadReadHost) ListPendingToolSettlementTargets(ctx context.Context, threadID ThreadID) ([]PendingToolSettlementTarget, error)

ListPendingToolSettlementTargets returns all canonical active pending tool targets for the bound root thread. The result is complete and unpaginated.

func (*ThreadReadHost) ListThreadDetailEvents added in v0.15.0 

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

func (*ThreadReadHost) ListThreadTurns added in v0.15.0 

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

func (*ThreadReadHost) ReadApprovalQueue added in v0.21.0 

func (h *ThreadReadHost) ReadApprovalQueue(ctx context.Context, req ReadApprovalQueueRequest) (ApprovalQueue, error)

func (*ThreadReadHost) ReadArtifact added in v0.18.0 

func (h *ThreadReadHost) ReadArtifact(ctx context.Context, req ReadArtifactRequest) (ArtifactContent, error)

ReadArtifact reads one artifact owned by the exact root thread bound to this capability.

func (*ThreadReadHost) ReadLatestThreadTurn added in v0.15.0 

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

func (*ThreadReadHost) ReadThread added in v0.15.0 

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

func (*ThreadReadHost) ReadThreadAgentTodos added in v0.15.0 

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

func (*ThreadReadHost) ReadThreadContext added in v0.15.0 

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

func (*ThreadReadHost) ReadThreadOverview added in v0.15.0 

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

func (*ThreadReadHost) ReadThreadTurn added in v0.31.0 

func (h *ThreadReadHost) ReadThreadTurn(ctx context.Context, req ReadThreadTurnRequest) (ThreadTurnSnapshot, error)

ReadThreadTurn returns one canonical turn bound to this root read host.

func (*ThreadReadHost) ReadTurnProjection added in v0.15.0 

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

type ThreadReadHostBinder added in v0.18.0 

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

ThreadReadHostBinder issues only root-thread read handles.

func NewThreadReadHostBinder added in v0.18.0 

func NewThreadReadHostBinder(bootstrap *HostBootstrap) (*ThreadReadHostBinder, error)

NewThreadReadHostBinder constructs the root-thread read issuer.

func (*ThreadReadHostBinder) NewHost added in v0.18.0 

func (b *ThreadReadHostBinder) NewHost(ctx context.Context, threadID ThreadID) (*ThreadReadHost, error)

NewHost constructs read authority for exactly one root thread.

type ThreadSnapshot added in v0.3.0 

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

func (ThreadSnapshot) Validate added in v0.29.0 

func (s ThreadSnapshot) Validate() error

Validate checks the complete public thread snapshot contract.

type ThreadStatus added in v0.3.0 

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

func (ThreadStatus) Valid added in v0.29.0 

func (s ThreadStatus) Valid() bool

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

type ThreadSummary added in v0.3.44 

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

func (ThreadSummary) Validate added in v0.29.0 

func (s ThreadSummary) Validate() error

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

type ThreadTitleHost added in v0.15.0 

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

ThreadTitleHost writes the canonical title for one bound root thread.

func (*ThreadTitleHost) SetThreadTitle added in v0.15.0 

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

type ThreadTitleHostBinder added in v0.18.0 

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

ThreadTitleHostBinder issues only root-thread title handles.

func NewThreadTitleHostBinder added in v0.18.0 

func NewThreadTitleHostBinder(bootstrap *HostBootstrap) (*ThreadTitleHostBinder, error)

NewThreadTitleHostBinder constructs the root-thread title issuer.

func (*ThreadTitleHostBinder) NewHost added in v0.18.0 

func (b *ThreadTitleHostBinder) NewHost(ctx context.Context, threadID ThreadID, sink EventSink) (*ThreadTitleHost, error)

NewHost constructs title authority for exactly one root thread.

type ThreadTitleMode added in v0.6.0 

type ThreadTitleMode string

ThreadTitleMode selects who owns durable thread title generation. 

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

type ThreadTitleSource added in v0.29.0 

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 added in v0.29.0 

func ParseThreadTitleSource(raw string) (ThreadTitleSource, error)

ParseThreadTitleSource validates raw public title source text.

func (ThreadTitleSource) Valid added in v0.29.0 

func (s ThreadTitleSource) Valid() bool

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

type ThreadTitleStatus added in v0.29.0 

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 added in v0.29.0 

func ParseThreadTitleStatus(raw string) (ThreadTitleStatus, error)

ParseThreadTitleStatus validates raw public title status text.

func (ThreadTitleStatus) Valid added in v0.29.0 

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 added in v0.29.0 

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 added in v0.20.0 

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

func (ThreadTurnFailure) Validate added in v0.20.0 

func (f ThreadTurnFailure) Validate() error

type ThreadTurnFailureCode added in v0.20.0 

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

func (ThreadTurnFailureCode) Valid added in v0.20.0 

func (c ThreadTurnFailureCode) Valid() bool

type ThreadTurnProjection added in v0.3.49 

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

func ProjectThreadTurn added in v0.3.49 

func ProjectThreadTurn(req ProjectThreadTurnRequest) ThreadTurnProjection

func (ThreadTurnProjection) Validate added in v0.7.0 

func (p ThreadTurnProjection) Validate() error

type ThreadTurnProjectionSegment added in v0.3.49 

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

type ThreadTurnProjectionSegmentKind added in v0.3.49 

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

type ThreadTurnProjectionSignal added in v0.3.49 

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

type ThreadTurnRetrySource added in v0.20.0 

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

type ThreadTurnSnapshot added in v0.11.0 

type ThreadTurnSnapshot struct {
	TurnID    TurnID    `json:"turn_id"`
	RunID     RunID     `json:"run_id"`
	Ordinal   int64     `json:"ordinal"`
	StartedAt time.Time `json:"started_at"`
	UpdatedAt time.Time `json:"updated_at"`
	// UserEntryID 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 added in v0.31.0 

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 added in v0.11.0 

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

func (ThreadTurnsPage) Validate added in v0.31.0 

func (p ThreadTurnsPage) Validate() error

Validate checks one public turn page without consulting persisted state.

type ThreadUserMessageOrigin added in v0.30.0 

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 ToolSurface added in v0.3.40 

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

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

type ToolSurfaceProvider added in v0.3.40 

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

type ToolSurfaceRequest added in v0.3.40 

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

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

type TraceID added in v0.3.0 

type TraceID string

type TurnCompletionPolicy added in v0.3.1 

type TurnCompletionPolicy string

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

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

type TurnExecutionHost added in v0.17.0 

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

TurnExecutionHost owns provider-backed turn admission and continuation for one canonical thread.

func (*TurnExecutionHost) CompletePendingTool added in v0.17.0 

func (h *TurnExecutionHost) CompletePendingTool(ctx context.Context, req PendingToolCompletionRequest) (PendingToolCompletionResult, error)

func (*TurnExecutionHost) ReadApprovalQueue added in v0.20.0 

func (h *TurnExecutionHost) ReadApprovalQueue(ctx context.Context, req ReadApprovalQueueRequest) (ApprovalQueue, error)

func (*TurnExecutionHost) ResolveApproval added in v0.20.0 

func (h *TurnExecutionHost) ResolveApproval(ctx context.Context, req ResolveApprovalRequest) (ResolveApprovalResult, error)

func (*TurnExecutionHost) RetryTurn added in v0.17.0 

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

func (*TurnExecutionHost) RunTurn added in v0.17.0 

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

func (*TurnExecutionHost) SettlePendingTool added in v0.18.0 

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

func (*TurnExecutionHost) UpdateThreadAgentTodos added in v0.17.0 

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

type TurnExecutionHostBinder added in v0.18.0 

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

TurnExecutionHostBinder issues only thread-bound turn factories.

func NewTurnExecutionHostBinder added in v0.18.0 

func NewTurnExecutionHostBinder(bootstrap *HostBootstrap) (*TurnExecutionHostBinder, error)

NewTurnExecutionHostBinder constructs the turn execution issuer.

func (*TurnExecutionHostBinder) Bind added in v0.18.0 

func (b *TurnExecutionHostBinder) Bind(threadID ThreadID) (*TurnExecutionHostFactory, error)

Bind constructs provider-backed turn capability factory for exactly one root thread.

type TurnExecutionHostFactory added in v0.17.0 

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

TurnExecutionHostFactory issues thread-bound turn execution capabilities.

func (*TurnExecutionHostFactory) NewHost added in v0.17.0 

func (f *TurnExecutionHostFactory) NewHost(ctx context.Context, opts TurnExecutionHostOptions) (*TurnExecutionHost, error)

NewHost constructs a provider-backed capability for one existing root thread.

type TurnExecutionHostOptions added in v0.17.0 

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

TurnExecutionHostOptions configures one thread-bound turn capability.

func NewTurnExecutionHostOptions added in v1.0.0 

func NewTurnExecutionHostOptions(cfg config.Config, options ...TurnExecutionOption) (TurnExecutionHostOptions, error)

NewTurnExecutionHostOptions constructs validated options without changing the authority or lifecycle of TurnExecutionHost.

type TurnExecutionOption added in v0.28.0 

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

TurnExecutionOption is an opaque option for one turn execution capability. Valid values are returned only by this package's With functions.

func WithTurnCapabilities added in v1.0.0 

func WithTurnCapabilities(capabilities CapabilityOptions) TurnExecutionOption

WithTurnCapabilities configures product-neutral runtime capability sources.

func WithTurnDynamicToolSurface added in v1.0.0 

func WithTurnDynamicToolSurface(provider ToolSurfaceProvider) TurnExecutionOption

WithTurnDynamicToolSurface configures the existing per-step tool surface owner.

func WithTurnEffectfulTools added in v1.0.0 

func WithTurnEffectfulTools(registry *tools.Registry, gate EffectAuthorizationGate) TurnExecutionOption

WithTurnEffectfulTools configures the explicit effect authorization path.

func WithTurnEventSink added in v1.0.0 

func WithTurnEventSink(sink EventSink) TurnExecutionOption

WithTurnEventSink observes the existing runtime event contract.

func WithTurnIDGenerator added in v1.0.0 

func WithTurnIDGenerator(generator func(string) string) TurnExecutionOption

WithTurnIDGenerator supplies deterministic correlation identifiers. It does not derive ThreadID, TurnID, RunID, or PromptScopeID values.

func WithTurnLoopLimits added in v1.0.0 

func WithTurnLoopLimits(limits LoopLimits) TurnExecutionOption

WithTurnLoopLimits configures turn loop limits.

func WithTurnModelGateway added in v1.0.0 

func WithTurnModelGateway(gateway ModelGateway, identity ModelGatewayIdentity, capabilities ModelGatewayCapabilities) TurnExecutionOption

WithTurnModelGateway atomically configures a custom gateway and its declared identity and capabilities.

func WithTurnReadOnlyTools added in v1.0.0 

func WithTurnReadOnlyTools(items ...tools.Tool) TurnExecutionOption

WithTurnReadOnlyTools configures an immutable registry snapshot after proving every tool is locally read-only and statically allowed.

func WithTurnThreadTitleMode added in v1.0.0 

func WithTurnThreadTitleMode(mode ThreadTitleMode) TurnExecutionOption

WithTurnThreadTitleMode selects host-owned or provider-owned title generation.

type TurnID added in v0.3.0 

type TurnID string

type TurnInput added in v0.12.0 

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

func (TurnInput) Validate added in v0.12.0 

func (i TurnInput) Validate() error

type TurnLimits added in v0.3.1 

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

TurnLimits contains per-run budget and continuation caps.

type TurnProjectionAvailability added in v0.7.0 

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

func (TurnProjectionAvailability) Valid added in v0.7.0 

func (a TurnProjectionAvailability) Valid() bool

type TurnResult added in v0.3.0 

type TurnResult struct {
	ThreadID               ThreadID                       `json:"thread_id"`
	TurnID                 TurnID                         `json:"turn_id"`
	RunID                  RunID                          `json:"run_id"`
	Status                 TurnStatus                     `json:"status"`
	Output                 string                         `json:"output,omitempty"`
	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 added in v0.10.0 

func (r TurnResult) Validate() error

type TurnSignal added in v0.3.1 

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

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

func ProjectCoreControlSignal added in v0.3.10 

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

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

type TurnSignalSpec added in v0.3.1 

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

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

type TurnStatus added in v0.3.0 

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

func (TurnStatus) IsTerminal added in v0.7.0 

func (s TurnStatus) IsTerminal() bool

func (TurnStatus) Valid added in v0.7.0 

func (s TurnStatus) Valid() bool

type TurnSupplementalContextItem added in v0.3.89 

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

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

type UpdateThreadAgentTodosRequest added in v0.11.0 

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

type WaitSubAgentsRequest added in v0.3.17 

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

type WaitSubAgentsResult added in v0.3.17 

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

func (WaitSubAgentsResult) Validate added in v1.0.0 

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.