taskengine

type ApprovalPendingError struct {
	// ApprovalID is the durable approval row's ID and the checkpoint key.
	ApprovalID string
	ToolName   string
}

type AttentionAnswer struct {
	Answered bool
	Text     string
}

type AudioPart struct {
	// Data is the raw audio bytes. JSON encoding carries it as standard base64.
	Data []byte `json:"data"`
	// MimeType is the audio media type.
	MimeType string `json:"mime_type" example:"audio/wav"`
}

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

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

type CapturedPayloadSummary struct {
	Truncated         bool   `json:"truncated"`
	Reason            string `json:"reason"`
	OriginalType      string `json:"originalType,omitempty"`
	OriginalJSONBytes int    `json:"originalJsonBytes,omitempty"`
	SHA256            string `json:"sha256,omitempty"`
	Preview           string `json:"preview,omitempty"`
	PreviewBytes      int    `json:"previewBytes,omitempty"`
}

type CapturedStateUnit struct {
	// Scope is the unit's hierarchical address (chain + task), matching the address contract TaskEvent carries.
	Scope       EventScope    `json:"scope,omitzero"`
	TaskID      string        `json:"taskID" example:"validate_input"`
	TaskHandler string        `json:"taskHandler" example:"chat_completion"`
	InputType   DataType      `json:"inputType" example:"string" openapi_include_type:"string"`
	OutputType  DataType      `json:"outputType" example:"string" openapi_include_type:"string"`
	Transition  string        `json:"transition" example:"valid_input"`
	Duration    time.Duration `json:"duration" example:"452000000"`
	Error       ErrorResponse `json:"error" openapi_include_type:"taskengine.ErrorResponse"`
	Input       any           `json:"input,omitempty"`
	Output      any           `json:"output,omitempty"`
	InputVar    string        `json:"inputVar" example:"input"`

	RetryIndex   int         `json:"retryIndex"`
	Cancelled    bool        `json:"cancelled,omitempty"`
	TimedOut     bool        `json:"timedOut,omitempty"`
	ProviderType string      `json:"providerType,omitempty"`
	ModelName    string      `json:"modelName,omitempty"`
	ToolNames    []string    `json:"toolNames,omitempty"`
	TokenUsage   *TokenUsage `json:"tokenUsage,omitempty"`
	// FinishReason is the provider's verbatim finish reason for the model call this step captured, when the output was a chat history.
	FinishReason string `json:"finishReason,omitempty"`
}

type ChainContext struct {
	Tools       map[string]ToolWithResolution
	ClientTools []Tool
	Debug       bool
}

type ChainSuspendedError struct {
	ApprovalID string
	// Scope is the hierarchical address of the interrupt point.
	Scope EventScope
}

type ChainTerms string

type ChatHistory struct {
	// Messages is the list of messages in the conversation.
	Messages []Message `json:"messages"`
	// Model is the name of the model to use for the conversation.
	Model string `json:"model" example:"llama2:7b"`
	// InputTokens will be filled by the engine and will hold the number of tokens used for the input.
	InputTokens int `json:"inputTokens" example:"15"`
	// OutputTokens will be filled by the engine and will hold the number of tokens used for the output.
	OutputTokens int `json:"outputTokens" example:"10"`
	// FinishReason is the provider's verbatim finish reason for the last model
	// call ("length"-class means truncated); empty when none reported.
	FinishReason string `json:"finishReason,omitempty" example:"stop"`
}

type Checkpoint struct {
	ApprovalID   string
	PendingCalls []PendingToolCall
	// Chain is the full definition as executed: chains are data, so a
	// reference could dangle across a restart, but the definition cannot.
	Chain      *TaskChainDefinition
	TaskID     string
	RetryIndex int
	Scope      EventScope
	// Vars/VarTypes round-trip through the closed DataType enum (see
	// decodeCheckpointVar) — no reflection.
	Vars       map[string]any
	VarTypes   map[string]DataType
	EdgeCounts map[string]int
	// History ends with the unanswered tool calls (plus any results
	// produced before the gate) — the shape the tool-pairing repair path
	// re-enters on.
	History           ChatHistory
	TemplateVars      map[string]string
	ToolsAllowlist    []string
	HasToolsAllowlist bool
	ContextLength     int
	SessionID         string
	MissionID         string
	RequestID         string
	ChainRef          string
	CreatedAt         time.Time
}

type CheckpointSaver interface {
	SaveCheckpoint(ctx context.Context, cp *Checkpoint) error
}

type DataType int

type EnvExecutor interface {
	ExecEnv(ctx context.Context, chain *TaskChainDefinition, input any, dataType DataType) (any, DataType, []CapturedStateUnit, error)
}

type ErrorResponse struct {
	ErrorInternal error  `json:"-"`
	Error         string `json:"error" example:"validation failed: input contains prohibited content"`
}

type EventScope struct {
	Chain    string `json:"chain,omitempty"`
	Task     string `json:"task,omitempty"`
	ToolCall string `json:"tool_call,omitempty"`
}

type FunctionCall struct {
	Name      string `json:"name" example:"get_current_weather"`
	Arguments string `json:"arguments" example:"{\n  \"location\": \"San Francisco, CA\",\n  \"unit\": \"celsius\"\n}"`
}

type FunctionCallObject struct {
	Name      string `json:"name" example:"get_current_weather"`
	Arguments any    `json:"arguments"`
}

type FunctionTool struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Parameters  interface{} `json:"parameters,omitempty"` // JSON Schema object
}

type GateResult struct {
	Value any
	Type  DataType
}

type GateResultRecorder func(ctx context.Context, approvalID string, result GateResult) error

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

type HandlerOutputMode int

type HandlerSignature struct {
	// Inputs is the closed set of DataTypes the handler accepts, in the order teaching
	// errors name them; empty means every DataType is accepted.
	Inputs []DataType
	// Mode says how the success-output type derives from the input type.
	Mode HandlerOutputMode
	// Output is the produced type when Mode == HandlerOutputFixed.
	Output DataType
	// SuccessEvals is the closed transition-eval vocabulary the handler can emit on
	// success — the only values a TransitionBranch can match; nil means the vocabulary
	// is open and the linter cannot prove a branch dead.
	SuccessEvals []string
}

type ImagePart struct {
	// Data is the raw image bytes. JSON encoding carries it as standard base64.
	Data []byte `json:"data"`
	// MimeType is the image media type.
	MimeType string `json:"mime_type" example:"image/png"`
}

type Inspector interface {
	Start(ctx context.Context) StackTrace
}

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

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

type LLMExecutionConfig struct {
	// Model is the primary model, placed first in the candidate list and used
	// for token counting; Model plus Models form the full candidate set.
	Model string `yaml:"model" json:"model" example:"llama2:7b"`
	// Models is an additional candidate pool, considered alongside Model.
	Models []string `yaml:"models,omitempty" json:"models,omitempty" example:"[\"gpt-4\", \"gpt-3.5-turbo\"]"`
	// Provider is the primary provider, placed first in the candidate list;
	// Providers supplies additional candidates.
	Provider  string   `yaml:"provider,omitempty" json:"provider,omitempty" example:"ollama"`
	Providers []string `yaml:"providers,omitempty" json:"providers,omitempty" example:"[\"ollama\", \"openai\"]"`
	// Temperature is the sampling temperature; nil means unset (provider
	// default for chat_completion, 0.0 for prompt/route).
	Temperature *float32 `yaml:"temperature,omitempty" json:"temperature,omitempty" example:"0.7"`
	// Tools is the allowlist of registry tool names this task may invoke
	// ("*" exposes all, "*","!name" excludes name(s)); client-passed tools are
	// governed separately by PassClientsTools.
	Tools []string `yaml:"tools,omitempty" json:"tools,omitempty" example:"[\"local_shell\", \"nws\"]"`
	// HideTools suppresses specific tools by (namespaced) name from BOTH the
	// registry tools selected via Tools and the client-passed tools.
	HideTools []string `yaml:"hide_tools,omitempty" json:"hide_tools,omitempty" example:"[\"tool1\", \"tools_name1.tool1\"]"`
	// ToolsPolicies carries per-tools policy overrides for this task (tools
	// name -> policy key -> value), injected into context before
	// GetToolsForToolsByName.
	ToolsPolicies    map[string]map[string]string `yaml:"tools_policies,omitempty" json:"tools_policies,omitempty"`
	PassClientsTools bool                         `yaml:"pass_clients_tools" json:"pass_clients_tools"`
	// Think controls reasoning mode (auto, off, minimal, low, medium, high,
	// xhigh, or a boolean-style alias); empty uses the provider default.
	Think string `yaml:"think,omitempty" json:"think,omitempty" example:"high"`
	// MaxTokens caps the model's output tokens; unset sends no explicit cap
	// and never falls back to the chain's TokenLimit, which bounds input+output.
	MaxTokens *int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty" example:"8192"`
	// MaxTokensTemplate stores a string max_tokens macro from chain JSON until
	// MacroEnv expands it into MaxTokens.
	MaxTokensTemplate string `yaml:"-" json:"-"`
	// Shift allows the context window to slide on overflow instead of erroring.
	Shift bool `yaml:"shift,omitempty" json:"shift,omitempty"`
	// RetryPolicy wraps the chat/prompt call with classified retry and an
	// optional model fallback; nil disables retry.
	RetryPolicy *llmretry.RetryPolicy `yaml:"retry_policy,omitempty" json:"retry_policy,omitempty"`
}

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

type Message struct {
	// ID is not used by the engine; useful for tracking messages and diffing
	// histories before storage.
	ID      string `json:"id" example:"msg_123456"`
	Role    string `json:"role" example:"user"`
	Content string `json:"content,omitempty" example:"What is the capital of France?"`
	// Images travel with Content to the model; image-bearing requests resolve
	// only to vision-capable models.
	Images []ImagePart `json:"images,omitempty" openapi_include_type:"taskengine.ImagePart"`
	// Audio travels with Content to the model; audio-bearing requests resolve
	// only to audio-capable models.
	Audio []AudioPart `json:"audio,omitempty" openapi_include_type:"taskengine.AudioPart"`
	// Thinking is the model's internal reasoning trace, populated only when
	// thinking is enabled; never sent back to the model as history.
	Thinking   string     `json:"thinking,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
	CallTools  []ToolCall `json:"callTools,omitempty"`
	Timestamp  time.Time  `json:"timestamp" example:"2023-11-15T14:30:45Z"`
	// RequestID and ChainRef are turn provenance (the run's X-Request-ID and
	// the chain path that ran it), not used by the engine.
	RequestID string `json:"requestId,omitempty"`
	ChainRef  string `json:"chainRef,omitempty"`
}

type MockTaskExecutor struct {
	// Single value responses
	MockOutput          any
	MockTransitionValue string
	MockError           error

	// Sequence responses
	MockOutputSequence          []any
	MockTaskTypeSequence        []DataType
	MockTransitionValueSequence []string
	ErrorSequence               []error

	// Tracking
	CalledWithTask   *TaskDefinition
	CalledWithInput  any
	CalledWithPrompt string
	// contains filtered or unexported fields
}

type NoopTaskEventSink struct{}

type OperatorTerm string

type PendingToolCall struct {
	CallID    string `json:"call_id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

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

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

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

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

type StackTrace interface {
	RecordStep(step CapturedStateUnit)
	GetExecutionHistory() []CapturedStateUnit
}

type TaskChainDefinition struct {
	ID string `yaml:"id" json:"id" jsonschema:"required"`

	// Debug enables capturing user input and output.
	Debug bool `yaml:"debug" json:"debug"`

	Description string `yaml:"description" json:"description"`

	Tasks []TaskDefinition `yaml:"tasks" json:"tasks" openapi_include_type:"taskengine.TaskDefinition" jsonschema:"required,minItems=1"`

	// TokenLimit is the token limit for the context window used during execution.
	TokenLimit int64 `yaml:"token_limit" json:"token_limit"`
}

type TaskDefinition struct {
	ID string `yaml:"id" json:"id" example:"validate_input" jsonschema:"required"`

	Description string `yaml:"description" json:"description" example:"Validates user input meets quality requirements"`

	// Handler determines how the LLM output (or tools) will be interpreted.
	Handler TaskHandler `yaml:"handler" json:"handler" example:"chat_completion" openapi_include_type:"string" jsonschema:"required"`

	SystemInstruction string `` /* 158-byte string literal not displayed */

	ExecuteConfig *LLMExecutionConfig `yaml:"execute_config,omitempty" json:"execute_config,omitempty" openapi_include_type:"taskengine.LLMExecutionConfig"`

	// Tools defines an external action to run: required for Tools tasks, nil
	// for all other types.
	Tools *ToolsCall `yaml:"tools,omitempty" json:"tools,omitempty" openapi_include_type:"taskengine.ToolsCall"`

	// Print optionally formats the output for display/logging, supporting
	// template variables from previous task outputs.
	Print string `yaml:"print,omitempty" json:"print,omitempty" example:"Validation result: {{.validate_input}}"`

	// PromptTemplate, when set, overrides the resolved input as the prompt
	// sent to the LLM.
	PromptTemplate string `yaml:"prompt_template,omitempty" json:"prompt_template,omitempty" example:"Is this input valid? {{.input}}"`

	// OutputTemplate, when set, renders a tools task's JSON output through
	// this go template; the rendered string becomes the task's output.
	OutputTemplate string `yaml:"output_template,omitempty" json:"output_template,omitempty" example:"Tools result: {{.status}}"`

	// InputVar names the variable to use as this task's input; each task
	// stores its own output in a variable named after its task id.
	InputVar string `yaml:"input_var,omitempty" json:"input_var,omitempty" example:"input"`

	// InputMaxBytes caps oversized string/chat-history inputs before this task runs.
	InputMaxBytes int `yaml:"input_max_bytes,omitempty" json:"input_max_bytes,omitempty" example:"8192"`

	// Transition defines what to do after this task completes.
	Transition TaskTransition `yaml:"transition" json:"transition" openapi_include_type:"taskengine.TaskTransition"`

	// Timeout is a Go duration string ("10s", "2m") bounding task execution.
	Timeout string `yaml:"timeout,omitempty" json:"timeout,omitempty" example:"30s"`

	// RetryOnFailure sets how many times to retry this task on failure (all
	// task types); 0 means no retries.
	RetryOnFailure int `yaml:"retry_on_failure,omitempty" json:"retry_on_failure,omitempty" example:"2"`
}

type TaskEvent struct {
	Kind      TaskEventKind `json:"kind"`
	Timestamp time.Time     `json:"timestamp"`
	RequestID string        `json:"request_id,omitempty"`
	// Scope is the event's hierarchical address (chain/task/tool-call); additive on the wire alongside the legacy flat fields below.
	Scope        EventScope `json:"scope,omitzero"`
	ChainID      string     `json:"chain_id,omitempty"`
	TaskID       string     `json:"task_id,omitempty"`
	TaskHandler  string     `json:"task_handler,omitempty"`
	Retry        int        `json:"retry"`
	ModelName    string     `json:"model_name,omitempty"`
	ProviderType string     `json:"provider_type,omitempty"`
	BackendID    string     `json:"backend_id,omitempty"`
	OutputType   string     `json:"output_type,omitempty"`
	Transition   string     `json:"transition,omitempty"`
	Content      string     `json:"content,omitempty"`
	Thinking     string     `json:"thinking,omitempty"`
	Error        string     `json:"error,omitempty"`

	ApprovalID   string         `json:"approval_id,omitempty"`
	HookName     string         `json:"hook_name,omitempty"`
	ToolName     string         `json:"tool_name,omitempty"`
	ApprovalArgs map[string]any `json:"approval_args,omitempty"`
	ApprovalDiff string         `json:"approval_diff,omitempty"`

	HITLAction            string `json:"hitl_action,omitempty"`
	HITLReason            string `json:"hitl_reason,omitempty"`
	HITLPolicyName        string `json:"hitl_policy_name,omitempty"`
	HITLPolicyPath        string `json:"hitl_policy_path,omitempty"`
	HITLArgsSummary       string `json:"hitl_args_summary,omitempty"`
	HITLMatchedRule       *int   `json:"hitl_matched_rule,omitempty"`
	HITLTimeoutS          int    `json:"hitl_timeout_s,omitempty"`
	HITLApprovalRequested *bool  `json:"hitl_approval_requested,omitempty"`

	ToolDiffPath    string `json:"tool_diff_path,omitempty"`
	ToolDiffOldText string `json:"tool_diff_old_text,omitempty"`
	ToolDiffNewText string `json:"tool_diff_new_text,omitempty"`

	// For token_usage
	TokenUsed int `json:"token_used,omitempty"`
	TokenSize int `json:"token_size,omitempty"`

	// step_stream_end bracket: ChunkCount counts step_chunk parcels seen, FinishReason is the provider's verbatim reason, Usage is provider-reported token usage.
	ChunkCount   int         `json:"chunk_count,omitempty"`
	FinishReason string      `json:"finish_reason,omitempty"`
	Usage        *TokenUsage `json:"usage,omitempty"`
}

type TaskEventKind string

type TaskEventScope struct {
	ChainID     string
	TaskID      string
	TaskHandler string
	Retry       int
}

type TaskEventSink interface {
	PublishTaskEvent(ctx context.Context, event TaskEvent) error
	Wants(kind TaskEventKind) bool
}

type TaskExecutor interface {
	// TaskExec executes currentTask and returns its output, output type, and
	// transition-eval string; ctxLength bounds token usage.
	TaskExec(ctx context.Context, startingTime time.Time, ctxLength int, chainContext *ChainContext, currentTask *TaskDefinition, input any, dataType DataType) (any, DataType, string, error)
}

type TaskHandler string

type TaskTransition struct {
	// OnFailure is the task ID to jump to in case of failure.
	OnFailure string `yaml:"on_failure" json:"on_failure" example:"error_handler"`

	// Branches defines conditional branches for successful task completion.
	Branches []TransitionBranch `yaml:"branches" json:"branches" openapi_include_type:"taskengine.TransitionBranch"`
}

type TokenUsage struct {
	Prompt     int `json:"prompt"`
	Completion int `json:"completion"`
	Total      int `json:"total"`
}

type Tool struct {
	Type     string       `json:"type"`
	Function FunctionTool `json:"function"`
}

type ToolCall struct {
	ID       string       `json:"id" example:"call_abc123"`
	Type     string       `json:"type" example:"function"`
	Function FunctionCall `json:"function" openapi_include_type:"taskengine.FunctionCall"`
	// ProviderMeta carries opaque provider-specific data (e.g. Gemini thought_signature)
	// that must be round-tripped back on the next turn.
	ProviderMeta map[string]string `json:"provider_meta,omitempty" example:"{\"thought_signature\":\"123456\"}"`
}

type ToolWithResolution struct {
	Tool
	ToolsName string
}

type ToolsCall struct {
	// Name is the registered tools-PROVIDER (the service/server, e.g. "slack"),
	// not the tool; required.
	Name string `yaml:"name" json:"name" example:"slack"`

	// ToolName is the specific TOOL to invoke on that provider
	// (e.g. "send_slack_notification").
	ToolName string `yaml:"tool_name" json:"tool_name" example:"send_slack_notification"`
	// Args are key-value pairs passed to the tool call.
	Args map[string]string `` /* 126-byte string literal not displayed */
}

type ToolsProvider interface {
	ToolsRegistry
	ToolsWithSchema
}

type ToolsRegistry interface {
	Supports(ctx context.Context) ([]string, error)
}

type ToolsRepo interface {
	Exec(ctx context.Context, startingTime time.Time, input any, debug bool, args *ToolsCall) (any, DataType, error)
	ToolsRegistry
	ToolsWithSchema
}

type ToolsWithSchema interface {
	GetSchemasForSupportedTools(ctx context.Context) (map[string]*openapi3.T, error)
	GetToolsForToolsByName(ctx context.Context, name string) ([]Tool, error)
}

type TransitionBranch struct {
	// Operator defines how to compare the task's transition eval to When;
	// required, must be one of SupportedOperators(), and is byte-exact and
	// case-sensitive except for the `route` handler.
	Operator OperatorTerm `yaml:"operator,omitempty" json:"operator,omitempty" example:"equals" openapi_include_type:"string"`

	// When is the value this branch matches against the task's transition
	// eval; its meaning depends on the handler (a control token, or the
	// `route` handler's chosen label).
	When string `yaml:"when" json:"when" example:"tool_call"`

	// Goto specifies the target task ID if this branch is taken; empty or
	// taskengine.TermEnd ends the chain.
	Goto string `yaml:"goto" json:"goto" example:"positive_response"`

	// Edge identifies a graph edge "fromTaskID->toTaskID" consulted by
	// edge-state operators; required when Operator is one of those.
	Edge string `yaml:"edge,omitempty" json:"edge,omitempty" example:"chat->run_tools"`
}