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 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); the same
	// address contract TaskEvent carries, so checkpoints and replay name the
	// position of captured state without re-deriving it from loose IDs.
	// Additive JSON field; TaskID below stays populated identically.
	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 its output was a chat history ("length"-class
	// values mean truncation). Consumers normalize; the engine records.
	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 that produced this history ("length"-class values mean the response
	// was truncated). Filled by the engine; empty when no model call ran or
	// the provider reported none.
	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 HandlerOutputMode int

type HandlerSignature struct {
	// Inputs is the closed set of DataTypes the handler accepts, in the order
	// teaching errors should name them. Empty means the handler accepts every
	// DataType.
	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 ever match for
	// this handler. Nil means the vocabulary is open (route emits the model's
	// chosen label; a tools task's OutputTemplate replaces the eval with its
	// rendered text) 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: it is placed first in the candidate list and is
	// the model used for token counting (see GetPrimaryModel). When both Model and
	// Models are set, Model plus Models form the candidate set (Model first);
	// the resolver then picks a reachable one — so set exactly Model for a single
	// pinned model, or use Models for an explicit candidate pool.
	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; pointer so "unset" (nil) is
	// distinguishable from an explicit 0.0. When set it is honored everywhere.
	// When unset: chat_completion uses the provider default; the prompt/route
	// handlers use 0.0 (route depends on deterministic single-label output).
	Temperature *float32 `yaml:"temperature,omitempty" json:"temperature,omitempty" example:"0.7"`
	// Tools is the allowlist of registry tool names this task may invoke
	// (client-passed tools are governed separately by PassClientsTools):
	// absent/null/[] exposes none; ["*"] exposes all; ["a","b"] exposes only
	// those names (unknown ones ignored); ["*","!name"] excludes name(s),
	// meaningful only combined with "*".
	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 the context before
	// GetToolsForToolsByName so tools can render dynamic descriptions and
	// enforce the policy at Exec time.
	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 the
	// input+output window, not the output alone (conflating the two trips
	// per-model output limits, e.g. Vertex Gemini 2.5 Pro's 65536 cap).
	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. It is not emitted as a separate field.
	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 underlying chat/prompt call with classified retry
	// (rate-limit / server-error / timeout) and an optional model fallback.
	// Nil or zero-value disables retry — current default. See [llmretry.Do].
	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; it is useful for tracking messages and
	// computing differences of 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; requests with images
	// resolve only to vision-capable models and fail with a typed error
	// when none is available.
	Images []ImagePart `json:"images,omitempty" openapi_include_type:"taskengine.ImagePart"`
	// 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"`

	// 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"`

	// 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"`

	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"`

	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,
	// must be nil/omitted 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. Supports template variables from previous task outputs.
	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, for recovery/summarization tasks that should explain a failure
	// without re-feeding the huge input that caused it.
	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). It is
	// additive on the wire: consumers that predate it keep reading the flat
	// ChainID/TaskID fields below, which stay populated identically.
	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"`

	// For step_stream_end: the terminal bracket of one model stream.
	// ChunkCount is the number of parcels that carried visible content or
	// thinking (i.e. the number of step_chunk events a subscribed sink saw —
	// counted independently of Wants, so the bracket is truthful even when no
	// sink consumed chunks). FinishReason is the provider's verbatim finish
	// reason ("" on the non-streaming fallback, which reports none). Usage is
	// provider-reported token usage when available.
	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 against input/dataType and returns its
	// output, output type, and transition-eval string (see TaskTransition).
	// ctxLength bounds LLM token usage; startingTime anchors timing for the
	// whole chain run.
	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. It is
	// REQUIRED and must be one of SupportedOperators() — an empty or unknown
	// operator is rejected at chain validation (at runtime it would never match,
	// a silent dead branch). The comparison for equals/contains/starts_with/
	// ends_with is byte-exact and CASE-SENSITIVE with no trimming — a trailing
	// newline (common in multiline template literals) will not match. Only the
	// `route` handler normalizes its answer.
	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.
	// What the eval is depends on the handler:
	//   - chat_completion / execute_tool_calls / tools / noop → a control token,
	//     one of the Transition* constants (e.g. "tool_call", "executed",
	//     "tools_executed", "no_calls_found", "noop", "failed"). You CANNOT branch
	//     on the model's free text here — use the `route` handler for that.
	//   - route → the model's chosen label (one of the declared branch targets).
	//   - edge_traversed_at_least → an integer threshold (see that operator).
	When string `yaml:"when" json:"when" example:"tool_call"`

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

	// Edge identifies a graph edge "fromTaskID->toTaskID" whose traversal
	// count is consulted by edge-state operators (e.g. edge_traversed_at_least).
	// Required when Operator is one of those; ignored otherwise.
	Edge string `yaml:"edge,omitempty" json:"edge,omitempty" example:"chat->run_tools"`
}