agentloop

type AddArtifactArgs struct {
	Path     string            `json:"path"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type AddTodoArgs struct {
	Todos []TodoItemInput `json:"todos"`
}

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

type AgentConfig struct {
	// Name is an optional identifier for the agent used in logs.
	// If empty, defaults to "AgentLoop".
	Name string

	// ModelName is the model identifier passed to the underlying OpenAI-compatible
	// provider (e.g. "qwen3-max").
	ModelName string

	// ApiKey is the API key for the model provider.
	ApiKey string

	// ApiUrl is the base URL of the OpenAI-compatible API endpoint.
	// If empty, defaults to agents.AliBailianIntlBaseURL (see [agents.NewOpenAIChatModel]).
	ApiUrl string

	// Temperature controls sampling randomness for the model.
	// If 0, defaults to 0.7.
	Temperature float32

	// MaxRunSteps limits the maximum number of ReAct rounds (tool-call cycles) the agent may execute.
	// Enforced directly by the agent loop's own round counter (not by Eino's internal step counter),
	// so it maps 1:1 to actual chat-model calls regardless of graph topology (e.g. whether OutputCheck
	// or tools are enabled).
	// If 0 or negative, defaults to 5.
	MaxRunSteps int

	// Language specifies the language for agent responses.
	// If empty, defaults to "English".
	Language string

	// LogOnStart controls whether the agent logs when it starts processing.
	// If nil, defaults to true.
	LogOnStart *bool

	// LogOnEnd controls whether the agent logs token stats when it finishes.
	// If nil, defaults to true.
	LogOnEnd *bool

	// LogInputs controls whether the agent logs input messages to the model.
	// If nil, defaults to false.
	LogInputs *bool

	// LogOutputs controls whether the agent logs model and tool output content.
	// If nil, defaults to true.
	LogOutputs *bool

	// Tools is a list of custom tools to add to the built-in tools.
	// Built-in tools are always registered; this field adds additional tools.
	//
	// Create custom tools using helper functions:
	//   - [NewToolFunc] - for simple tools with map-based arguments
	//   - [NewCtxAwareToolFunc] - for tools needing AgentContext (Store, Todos)
	//   - [NewTypedToolFunc] - for tools with typed struct arguments
	//   - [NewTypedCtxAwareToolFunc] - for tools with typed arguments and AgentContext
	Tools []Tool

	// SystemPrompt is an optional task prompt.
	// If provided, it will be prepended to the base system prompt.
	SystemPrompt string

	// BackendFactory is a factory function that creates a fresh FileStore for each execution.
	// If nil, a new TmpFileStore will be created for each execution.
	// This allows stateful backends to be created fresh per execution.
	BackendFactory func() FileStore

	// Timezone is the timezone offset in hours for time display (default: 0, UTC).
	Timezone float64

	// MaxTokens is the maximum number of tokens allowed in the conversation history.
	// When exceeded, old messages will be pruned (except system messages).
	// If 0 or negative, no token limit is enforced.
	// Default: 0 (no limit)
	MaxTokens int

	// EnableModelsFetch enables runtime fetching of model context window sizes
	// from models.dev when the model is not found in the build-time generated map.
	// Fetched results are cached in memory for the process lifetime.
	EnableModelsFetch bool

	// EnableFileTool enables the built-in file tools: read_file, write_file, edit_file,
	// list_directory, glob, and add_artifact. When false, these tools are not registered.
	// If nil, defaults to true.
	EnableFileTool *bool

	// EnableTodoTool enables the built-in todo tools: add_todo, update_todo, list_todos,
	// delete_todo. When false, these tools are not registered.
	// If nil, defaults to false.
	EnableTodoTool *bool

	// EnableBashTool enables the built-in bash tool, which executes shell scripts in a
	// sandboxed environment (github.com/mark3labs/go-bash). When the configured FileStore
	// implements DirBackedFileStore, the sandbox shares that store's real directory, so
	// bash can operate on files written via write_file/read_file. When false, the tool is
	// not registered. If nil, defaults to false.
	EnableBashTool *bool

	// BashToolOptions configures the built-in bash tool (timeout, network access). Only
	// used when EnableBashTool is true. See WithBashTimeout, WithBashNetwork.
	BashToolOptions []BashToolOption

	// ToolEventCallback is called synchronously for each tool invocation during execution.
	// Receives a ToolEvent with the tool name and raw JSON args before the tool runs.
	// Must not block for long — it runs within the agent graph execution.
	// If nil, no events are emitted.
	ToolEventCallback func(event ToolEvent)

	// Compaction enables LLM-based context compaction when the conversation history
	// approaches MaxTokens. Older messages are summarized into a structured checkpoint;
	// recent messages are kept verbatim. Requires MaxTokens to be set.
	// If nil, defaults to false.
	Compaction *bool

	// CompactPreserveRecentTokens is the token budget for the verbatim recent tail kept after compaction.
	// Messages within this budget (newest first) are sent to the model as-is; older messages are summarized.
	// When MaxTokens is known, defaults to max(2000, min(8000, MaxTokens * 0.25)) — i.e., 25% of the
	// context window, clamped between 2k and 8k tokens. Set explicitly to override.
	CompactPreserveRecentTokens int

	// ToolOffloadTokenLimit is the token threshold above which a tool result is
	// offloaded to the backend store and replaced with a short preview + file pointer.
	// The agent can recover the full content by calling the read_file tool on the
	// saved path. nil uses the default threshold of 20,000 tokens. Set to a non-nil
	// pointer to 0 to disable offloading entirely.
	//
	// The following tools are never offloaded regardless of size: read_file,
	// write_file, edit_file, list_directory, glob, grep, delete.
	ToolOffloadTokenLimit *int

	// ToolOffloadResultsPathPrefix is the FileStore path prefix for offloaded tool
	// results. Each offloaded result is written to:
	//   {ToolOffloadResultsPathPrefix}/{sanitized_tool_call_id}
	// Defaults to "/large_tool_results" when empty.
	ToolOffloadResultsPathPrefix string

	// EnableToolOffload controls whether large tool results are offloaded to the
	// backend store and replaced with a preview + file pointer.
	// If nil, defaults to true. Set to a non-nil pointer to false to disable.
	EnableToolOffload *bool

	// Middleware is an ordered list of middleware to apply to the agent loop.
	// Middlewares are called in registration order for BeforeAgent, AfterAgent,
	// SystemPromptFragment, and Tools; and composed into chains for WrapModelCall
	// and WrapToolCall. Middleware cannot be registered after NewAgent() returns.
	Middleware []Middleware

	// OutputCheck is an optional callback invoked on each plain-text (non-tool-call) assistant
	// response before the agent accepts it as the final output. If OutputCheck returns a non-nil
	// error, its message is inserted into the conversation as a user message and the chat model
	// is called again so it can self-correct.
	//
	// OutputCheck can be used for output format validation, quality checks, security screening,
	// or any other per-response review. If nil, no check is performed.
	OutputCheck OutputCheckFunc

	// EnableTrace enables per-node execution tracing. When true, each graph node's input and
	// output are JSON-marshaled and collected in TaskOutput.TraceLogs. ChatModel entries include
	// the full message history per call, so TraceLogs can grow large on long multi-turn runs.
	// If nil, defaults to false.
	EnableTrace *bool

	// EnableHitlInterruptTool registers the built-in interrupt_for_human tool, allowing
	// the LLM to pause execution by calling it directly. Only takes effect when HitlStore
	// is also set. When false, tools can still trigger HITL via [RequestHitlInterrupt].
	EnableHitlInterruptTool bool

	// HitlStore persists interrupted session state for later resumption via [Agent.Resume].
	// When set, HITL is automatically enabled: tools may call [RequestHitlInterrupt] to
	// pause execution; the agent persists its state and returns TaskOutput.Interrupted = true.
	HitlStore HitlStore

	// Log user query, default true
	LogQuery *bool

	// ContentModeration is an optional callback to screen content at the boundary of agent execution.
	// It is called twice per Execute/Resume: once with contentType="INPUT" before the agent runs
	// (screening the user input), and once with contentType="OUTPUT" after the agent runs
	// (screening the agent's response). Returning ok=false aborts execution and surfaces the
	// reason as an error. If nil, no moderation is applied.
	ContentModeration ContentModerationFunc
}

type AgentContext struct {
	SessionId string
	UserInput string
	Store     FileStore
	Todos     *TodoManager
	Artifacts *ArtifactManager
	Metadata  *MetadataStore
	// contains filtered or unexported fields
}

type AgentRequest struct {
	// SessionId is an optional identifier for this execution.
	// If empty, a unique ID is generated automatically with the prefix "sess_".
	SessionId           string
	UserInput           string
	PreloadBackendFiles func(store FileStore) error                       // Optional callback to preload files into the backend before execution
	ArtifactCallback    func(store FileStore, artifacts []Artifact) error // Optional callback for artifacts
}

type AgentSpec struct {
	// Name identifies the sub-agent; used by the LLM to select which agent to call.
	Name         string
	Capabilities string
	Builder      func(AgentContext) (*Agent, error)
}

type Artifact struct {
	Path        string            // Backend file path
	SizeInBytes int64             // File size in bytes
	Meta        map[string]string // Additional metadata (title, url, etc.)
}

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

type AutoTypedCtxAwareToolFunc[T any] struct {
	// contains filtered or unexported fields
}

type BaseMiddleware struct{}

type BashArgs struct {
	Script string `json:"script"`
}

type BashToolOption func(*bashToolConfig)

type BuiltinToolsOption struct {
	// EnableFileTool enables the file-related tools: read_file, write_file, edit_file,
	// list_directory, glob, and add_artifact. Default: false.
	EnableFileTool bool

	// EnableTodoTool enables the todo management tools: add_todo, update_todo, list_todos,
	// delete_todo. Default: false.
	EnableTodoTool bool
}

type CommandContext = command.Context

type CommandResult = command.Result

type ContentModerationFunc func(content string, contentType string) (intendedOutput string, ok bool)

type DeleteTodoArgs struct {
	IDs []string `json:"ids"`
}

type DirBackedFileStore interface {
	FileStore
	// RootDir returns the real directory backing this store, creating it if needed.
	RootDir() (string, error)
}

type EditFileArgs struct {
	Path       string `json:"path"`
	OldString  string `json:"old_string"`
	NewString  string `json:"new_string"`
	ReplaceAll bool   `json:"replace_all,omitempty"`
}

type FileInfo struct {
	Path       string    `json:"path"`
	IsDir      bool      `json:"is_dir"`
	Size       int64     `json:"size"`
	ModifiedAt time.Time `json:"modified_at"`
}

type FileStore interface {
	// ReadFile reads a file from the backend.
	ReadFile(ctx context.Context, path string) ([]byte, error)

	// WriteFile writes content to a file in the backend.
	WriteFile(ctx context.Context, path string, content []byte) error

	// ListDirectory lists files and directories in a path.
	ListDirectory(ctx context.Context, path string) ([]FileInfo, error)

	// FileExists checks if a file exists.
	FileExists(ctx context.Context, path string) (bool, error)

	// DeleteFile deletes a file.
	DeleteFile(ctx context.Context, path string) error
}

type GlobArgs struct {
	Pattern string `json:"pattern"`
}

type HitlState struct {
	Messages            []*schema.Message
	CompactionSummary   string
	OutputCheckAttempts int
	InterruptReason     string
}

type HitlStore interface {
	// Save persists the HITL state for the given session.
	Save(ctx context.Context, sessionId string, state HitlState) error
	// Load retrieves the HITL state for the given session. existed=false if not found.
	Load(ctx context.Context, sessionId string) (state HitlState, existed bool, err error)
	// Delete removes the HITL state for the given session.
	Delete(ctx context.Context, sessionId string) error
}

type ListDirectoryArgs struct {
	Path string `json:"path"`
}

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

type MetadataView interface {
	Set(key string, value any)
	Get(key string) (any, bool)
	Delete(key string)
}

type Middleware interface {
	// Name returns a unique identifier for this middleware.
	// Used as the key for per-middleware private state storage.
	Name() string

	// BeforeAgent is called once at the start of Agent.Execute(),
	// before the graph begins running. Returning a non-nil error aborts execution.
	BeforeAgent(ctx context.Context, agentCtx AgentContext) error

	// WrapModelCall is called on every LLM invocation in the loop.
	// Use it to inject prompt fragments, filter messages, or observe the model response.
	WrapModelCall(ctx context.Context, req *ModelCallRequest, next ModelCallHandler) (*ModelCallResponse, error)

	// WrapToolCall is called for every tool execution.
	// Use it to intercept results, enforce permissions, or log tool calls.
	WrapToolCall(ctx context.Context, req *ToolCallRequest, next ToolCallHandler) (*ToolCallResponse, error)

	// AfterAgent is called once after Agent.Execute() finishes (success or error).
	// Errors from AfterAgent are logged but do not suppress the result.
	AfterAgent(ctx context.Context, agentCtx AgentContext, res *TaskOutput, err error) error

	// Tools returns additional tools this middleware contributes to the agent.
	// Called once at NewAgent() time; tools are merged into the shared ToolRegistry.
	Tools() []Tool

	// SystemPromptFragment returns a string to append to the system prompt.
	// Called once per Execute() during prompt assembly, after the user's custom
	// prompt but before the base ReAct prompt. Return empty string to contribute nothing.
	SystemPromptFragment(ctx context.Context) string
}

type ModelCallHandler func(ctx context.Context, req *ModelCallRequest) (*ModelCallResponse, error)

type ModelCallRequest struct {
	Messages []*schema.Message // Full message history sent to the model
	Task     string            // The original user task for this execution
}

type ModelCallResponse struct {
	Message *schema.Message // The assistant reply
}

type OutputCheckFunc func(ctx context.Context, agentCtx AgentContext, attempt int, output string) (hint string, ok bool, err error)

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

type ReadFileArgs struct {
	Path   string `json:"path"`
	Offset int    `json:"offset,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

type RedisHitlStoreOption func(*redisHitlStore)

type SelfInvokeTool interface {
	ExecuteJson(ctx context.Context, jsonArg string) (string, error)
}

type SessionAware interface {
	// OnSessionStart is called when an agent session begins, before any file operations.
	// Implementations should perform any initialisation here (e.g. creating a tmp directory).
	OnSessionStart(rail flow.Rail) error

	// OnSessionEnd is called when an agent session ends.
	// Implementations should release resources here (e.g. removing the tmp directory).
	OnSessionEnd(rail flow.Rail) error
}

type Skill struct {
	Metadata SkillMetadata
	Path     string
	Content  string // The markdown content (excluding YAML frontmatter)
}

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

type SkillMetadata struct {
	Name         string   `yaml:"name"`
	Description  string   `yaml:"description"`
	License      string   `yaml:"license,omitempty"`
	Compatible   string   `yaml:"compatibility,omitempty"`
	Metadata     string   `yaml:"metadata,omitempty"`
	AllowedTools []string `yaml:"allowed_tools,omitempty"`
}

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

type SkillsMap map[string]*Skill

type TaskOutput struct {
	Response   string         // Main response (research report)
	Artifacts  []Artifact     // Artifacts collected during execution
	Metadata   map[string]any // Snapshot of MetadataStore at end of execution
	TokenUsage TokenUsage     // Aggregate token usage across all LLM calls
	TraceLogs  []TraceEntry   // Per-node execution trace; populated when AgentConfig.EnableTrace is true, nil otherwise. Populated even when execution returns an error. ChatModel entries include the full message history per call, so size grows with each ReAct cycle.

	// Interrupted is true when the agent loop was paused for human input via HITL.
	// Use Agent.Resume to continue the session.
	Interrupted bool

	// InterruptReason is the human-readable reason for the interrupt provided by the tool.
	// Empty when Interrupted is false.
	InterruptReason string
}

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

type TodoItem struct {
	ID          string `json:"id"`
	Task        string `json:"task"`
	Status      string `json:"status"` // "pending", "completed"
	Description string `json:"description,omitempty"`
}

type TodoItemInput struct {
	Task        string `json:"task"`
	Description string `json:"description,omitempty"`
}

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

type TokenUsage struct {
	PromptTokens     int // Total input tokens consumed across all LLM calls
	CompletionTokens int // Total output tokens generated across all LLM calls
	CachedTokens     int // Total prompt tokens served from cache across all LLM calls
}

type Tokenizer struct{}

type Tool interface {
	// Name returns the name of the tool.
	Name() string

	// Description returns a description of the tool.
	Description() string

	// Parameters returns the JSON schema for the tool parameters.
	Parameters() map[string]*schema.ParameterInfo

	// Execute executes the tool with the given arguments.
	Execute(ctx context.Context, args map[string]interface{}) (string, error)
}

type ToolCallHandler func(ctx context.Context, req *ToolCallRequest) (*ToolCallResponse, error)

type ToolCallRequest struct {
	Name     string                 // Tool name
	Args     map[string]interface{} // Parsed arguments
	RawInput string                 // Original JSON string from the LLM
}

type ToolCallResponse struct {
	Result  string // String result returned to the LLM
	IsError bool   // When true, the result is an error message (LLM can self-correct)
}

type ToolEvent struct {
	Kind ToolEventKind
	Name string // tool name
	Args string // raw JSON args string
}

type ToolEventKind string

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

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

type TraceEntry struct {
	Node      string          `json:"node"`
	Component string          `json:"component"`
	Input     json.RawMessage `json:"input,omitempty"`
	Output    json.RawMessage `json:"output,omitempty"`
}

type TypedCtxAwareToolFunc[T any] struct {
	// contains filtered or unexported fields
}

type TypedToolFunc[T any] struct {
	// contains filtered or unexported fields
}

type UpdateTodoArgs struct {
	ID     string `json:"id,omitempty"`
	Status string `json:"status,omitempty"`
}

type WriteFileArgs struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}