tacklr

type AbsorbResult struct {
	// SummaryChunks are compress summaries to stream when StreamFitSummary is true.
	SummaryChunks []LLMResponseChunk
}

type Action int

type AgentOptions struct {
	Config Config
	// SessionID is the durable thread id. Set at construction; do not change mid-turn.
	SessionID string
	Model     InferenceStrategy
	WatchDog  AgentWatchDog
	// Tools are host tools, including optional builtins from package
	// builtins (email, Exa web). Give each tool its clients by closing
	// over them in the constructor (see NewTool). Session-world tools
	// (VFS, brain, index) still inject from the fields below.
	Tools      []*Tool
	MCPConfigs []mcp.MCPConfig
	// MCPCredentialResolver resolves durable references immediately before
	// connection. Inline client credentials remain session-scoped.
	MCPCredentialResolver mcp.CredentialResolver
	Specialists           []*Specialist
	// ContextPolicy sets pressure/compress ratios when non-zero fields are set.
	ContextPolicy ContextPolicy
	// ToolInterceptors wrap each tool call (outermost first). Built-in
	// planning lock and OnCall middleware are installed after these.
	// Hosts cannot omit the planning lock; specialists skip it via WithSpecialist.
	ToolInterceptors []ToolInterceptor
	// UnattendedWrite injects write without ToolPermissionOnCall.
	// Default false: write parks for permission.
	UnattendedWrite bool
	// ToolResultHooks map tool name → post-success window effects for host tools.
	// Plan builtins use ToolOutcome instead.
	ToolResultHooks map[string]ToolResultHook
	// SkillsLoader loads skills. When nil, SkillsSession is walked with
	// skills.Loader. MountSession is never used for skills.
	SkillsLoader skills.SkillLoader
	// SkillsSession is the host-only skills tree for this turn. Runtime
	// builds it from AgentSpec.OpenSkills. It is not session.VFS; VFS tools
	// do not see it. Nil and a nil SkillsLoader means no skills.
	SkillsSession *vfs.MountSession
	// SkillsRoot is the virtual directory skills.Loader walks on
	// SkillsSession. Empty means skills.DefaultRoot (/workspace/skills).
	SkillsRoot string
	// Brain enables knowledge builtins when non-nil. Workers inherit the same engine.
	// Configure Store, optional QueryEmbedder, and optional GraphReader/GraphWriter on the Engine
	// before NewTurnManager (e.g. brain.WithGraph(g) after helixgraph.New). The harness
	// does not construct store or graph backends.
	Brain *brain.Engine
	// BrainWriteKinds maps save_discovery / save_fact / save_memory to host kind names.
	// Empty fields skip that tool. Kinds should be registered via brain.ApplyKinds / WithKinds.
	// Ignored when Brain is nil.
	BrainWriteKinds brain.WriteKinds
	// SearchNamespace is the host ceiling for brain tools (session-owned, checkpointed).
	// Each tool call may add attrs to narrow the search; it cannot change ceiling values.
	// Empty means no ceiling. Workers get a copy at spawn.
	SearchNamespace brain.Namespace
	// MountSession is the agent /workspace tree for this turn, or nil (no VFS tools).
	// Runtime builds one from OpenVFS plus Prompt.Auth bindings when a
	// projection is available. Embedders pass their own. The injector Closes
	// it after the turn; the harness never does (workers inherit the pointer).
	// Do not mount skills here; use SkillsSession.
	MountSession *vfs.MountSession
	// UnattendedRunCommand injects run_command without ToolPermissionOnCall.
	// Default false: run_command parks for permission.
	UnattendedRunCommand bool
	// contains filtered or unexported fields
}

type AgentWatchDog interface {
	RecordOutput(*Message) error
	RecordToolResult(*Message) error
}

type Annotation struct {
	Type   string         `json:"type"`
	Text   string         `json:"text,omitempty"`
	FileID string         `json:"file_id,omitempty"`
	URL    *URLAnnotation `json:"url,omitempty"`
}

type Child struct {
	ID         string
	Specialist string
	State      string
	Result     string
}

type ChildHost interface {
	SpawnChild(ctx context.Context, specialist, task, callID string) (string, error)
	Children() []Child
	CancelChild(ctx context.Context, id string) error
	// AwaitChild waits or collects. A *interrupt.ChildWaiting error means the
	// child needs input: the wrapper Parks it. Other errors pass through.
	AwaitChild(ctx context.Context, id, callID string) (child Child, err error)
}

type Config struct {
	MaxWindowSize int
	SystemPrompt  string
	// MaxTurnRequests limits Model.Invoke calls per Run. 0 = unlimited.
	// Exceeding the limit ends the turn with ErrMaxTurnRequests.
	MaxTurnRequests int
}

type ContentPart struct {
	Type        string       `json:"type"`
	Text        string       `json:"text,omitempty"`
	Refusal     string       `json:"refusal,omitempty"`
	ImageURL    *ImageURL    `json:"image_url,omitempty"`
	FileData    *FileData    `json:"file_data,omitempty"`
	Annotations []Annotation `json:"annotations,omitempty"`
}

type ContextPolicy struct {
	// PressureRatio is the max-size fraction that triggers compress (for example 0.85).
	PressureRatio float64
	// CompressFraction seeds how much of the window to summarize.
	CompressFraction float64
	// StreamFitSummary streams compress summary chunks to the client when true.
	StreamFitSummary bool
}

type Engine interface {
	AbsorbUser(ctx context.Context, user *Message, out chan StreamEvent) error
	PendingToolCalls() []ToolCall
	RunInference(ctx context.Context, st *TurnState, out chan StreamEvent) (InferenceStep, error)
	RunToolCall(ctx context.Context, tc ToolCall, out chan StreamEvent) (ToolStep, error)
	ApplyResume(finishedInterrupts map[string][]byte) error
	// RecordToolResult appends a RoleTool message without executing (Temporal
	// after a child workflow already ran).
	RecordToolResult(tc ToolCall, output string)
	Messages() []*Message
}

type FileData struct {
	FileID   string `json:"file_id,omitempty"`
	URL      string `json:"url,omitempty"`
	Data     string `json:"data,omitempty"`
	MIMEType string `json:"mime_type,omitempty"`
	// Filename is preferred by providers for input_file (e.g. PDF data URLs).
	Filename string `json:"filename,omitempty"`
}

type HarnessRuntime interface {
	EmitUpdate(message string)
	StateGet(key string) (any, bool)
	StateSet(key string, value any) error
	StateDelete(key string)
	// Park writes pending for this tool call and returns the interrupt as
	// error. After Resume it returns the resolved interrupt and a nil error.
	Park(kind string, payload []byte) (Interrupt, error)
	CurrentToolCallID() string

	// SpawnChild starts a child of this session. It does not wait.
	// specialist must be registered on this session. The returned id is
	// unique for this session; pass it to Children, AwaitChild, CancelChild.
	SpawnChild(ctx context.Context, specialist, task string) (id string, err error)
	// Children lists this session's children. Waiting children appear as running.
	Children() []Child
	// CancelChild stops one child of this session and drops it from Children.
	CancelChild(ctx context.Context, id string) error
	// AwaitChild waits until a child completes or fails, then collects it
	// (it leaves Children). If the child needs user input, the call parks
	// like Park. Unknown ids return ErrNotFound.
	AwaitChild(ctx context.Context, id string) (Child, error)
}

type ImageURL struct {
	URL    string `json:"url"`
	Detail string `json:"detail,omitempty"`
}

type InferenceStep struct {
	ToolCalls []ToolCall
	Complete  bool
}

type InferenceStrategy interface {
	Invoke(ctx context.Context, messages []*Message, tools []*Tool, systemPrompt string) (chan LLMResponseChunk, error)
	CountTokens(context.Context, []*Message, []*Tool) (int, error)
	MaxContextWindow() (int, error)
	// SupportsMIME reports whether the currently selected model accepts the
	// given MIME type as user input. Empty and text/* are always true.
	// Probe representatives for ads (e.g. image/png); do not enumerate all types.
	SupportsMIME(mimeType string) bool
}

type Interrupt = interrupt.Interrupt

type ItemStatus string

type LLMResponseChunk struct {
	TurnId     string
	MessageId  string
	ToolCalls  []ToolCall
	Type       StreamEventType
	Content    string
	IsComplete bool
	// Error is set on terminal provider failures (Type == StreamEventError).
	// Harness copies it onto StreamEvent.Error so protocols can errors.Is
	// stop-reason sentinels (refusal, max_tokens, …).
	Error error

	// Token usage when the provider reports it (typically on StreamEventComplete
	// after response.completed). Zero means unknown / not reported.
	InputTokens     int
	OutputTokens    int
	ReasoningTokens int

	// EncryptedContent is Responses reasoning.encrypted_content. Provider parse
	// only; copied onto Message so the next turn can replay the item statelessly.
	EncryptedContent string
}

type Message struct {
	Role    MessageRole `json:"role"`
	Content string      `json:"content,omitempty"`

	// MessageID is the provider-assigned identifier for this output item,
	// used when serializing prior assistant or reasoning turns as typed
	// response items.
	MessageID string `json:"message_id,omitempty"`

	// EncryptedContent is the Responses API reasoning ciphertext
	// (include=reasoning.encrypted_content). Required to replay a reasoning
	// item by id without a provider store lookup.
	EncryptedContent string `json:"encrypted_content,omitempty"`

	ContentParts     []ContentPart `json:"content_parts,omitempty"`
	ToolCalls        []ToolCall    `json:"tool_calls,omitempty"`
	ToolCallID       string        `json:"tool_call_id,omitempty"`
	StructuredOutput any           `json:"-"`
}

type MessageRole string

type OnCallFunc func(ToolInvocation) Interrupt

type PayloadValidator = interrupt.PayloadValidator

type PendingToolCall struct {
	ToolCall        *ToolCall `json:"toolCall,omitempty"`
	InterruptActive bool      `json:"interruptActive,omitempty"`
}

type PermissionOption = interrupt.PermissionOption

type ProviderStatus interface {
	ProviderHTTPStatus() int
	ProviderErrorCode() string
}

type SessionCheckpoint struct {
	ContextWindow []*Message `json:"contextWindow"`
	// contains filtered or unexported fields
}

type Specialist struct {
	Tools        []*Tool
	Instructions string
	Model        InferenceStrategy
	Name         string
	Description  string
	// Specialists are nested workers available to this worker when it runs.
	Specialists []*Specialist
}

type StreamEvent struct {
	Type      StreamEventType
	TurnID    string
	MessageID string
	Content   string
	Data      []byte
	ToolCalls []ToolCall
	// Error is in-process only. Workflow Streams cannot encode error values;
	// Fail is the durable stand-in (sentinel Error() text).
	Error error  `json:"-"`
	Fail  string `json:"fail,omitempty"`
}

type StreamEventType string

type Todo struct {
	Title       string     `json:"title"`
	Status      TodoStatus `json:"status"`
	Description string     `json:"description"`
}

type TodoStatus string

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

type ToolAccess uint8

type ToolCall struct {
	ID        string       `json:"id,omitempty"`
	Type      string       `json:"type,omitempty"`
	CallID    string       `json:"call_id"`
	Name      string       `json:"name,omitempty"`  // programmatic tool id (model-facing)
	Title     string       `json:"title,omitempty"` // human-readable invocation label for UIs/protocols
	Category  ToolCategory `json:"category,omitempty"`
	Namespace string       `json:"namespace,omitempty"`
	Arguments string       `json:"arguments,omitempty"`
	Status    string       `json:"status,omitempty"`
}

type ToolCallFunc func(ctx context.Context, inv ToolInvocation) (string, error)

type ToolCategory string

type ToolConfig struct {
	Name        string
	Description string
	DisplayName string
	Namespace   string
	Category    ToolCategory
	Access      ToolAccess
	Timeout     time.Duration
	// OnCall is the pre-invoke middleware stack. Each constructor may park.
	// Return nil from a constructor to skip that layer. Types must be registered.
	OnCall []OnCallFunc

	// Handler is a Go function. Close over clients in the constructor that calls NewTool.
	// Optional parameters: context.Context, an args struct, HarnessRuntime.
	Handler any
}

type ToolHandlerFunc func(ctx context.Context, args map[string]any, runtime HarnessRuntime) (string, error)

type ToolInterceptor func(ctx context.Context, inv ToolInvocation, next ToolCallFunc) (string, error)

type ToolInvocation struct {
	Tool     *Tool
	ArgsJSON string
	Runtime  HarnessRuntime
}

type ToolOutcome struct {
	Output string
	// Effect is merged for the batch and applied once at batch end.
	Effect ToolResultEffect
	// SuppressWindowMessage omits the tool Message from the window.
	// The client still receives StreamEventToolResult.
	SuppressWindowMessage bool
}

type ToolPermission uint8

type ToolPermissionInterrupt = interrupt.ToolPermissionInterrupt

type ToolResultEffect int

type ToolResultHook func(ctx context.Context, obs ToolResultObservation) ToolOutcome

type ToolResultObservation struct {
	Name     string
	ArgsJSON string
	Output   string
	Runtime  HarnessRuntime
}

type ToolStep struct {
	Interrupted   bool
	InterruptID   string
	InterruptData []byte
}

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

type TurnState struct {
	ModelRequests int
	HadToolRound  bool
}

type URLAnnotation struct {
	URL   string `json:"url"`
	Title string `json:"title"`
}

type UserChoice = interrupt.UserChoice

type UserSelectionInterrupt = interrupt.UserSelectionInterrupt