dataflow

type AgentCaller interface {
	Ask(ctx context.Context, agentSlug, prompt string, tools []string, graphTools []ToolSpec) (string, error)
}

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

type Definition struct {
	Name        string `json:"name" yaml:"name"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Nodes       []Node `json:"nodes" yaml:"nodes"`
	// PinnedData freezes a node's output to a fixed set of items instead of
	// actually running it - Run checks this (keyed by node ID) before
	// invoking a node's own Execute, mirroring n8n's IPinData. Kept
	// separate from each Node's own Parameters, since "frozen test output"
	// is a different concept from real node configuration - a pinned
	// node's ValidateParameters/Execute (and even its registry lookup) are
	// never called at all, so a graph can be tested with a node whose real
	// config is incomplete, or whose type isn't implemented yet.
	PinnedData map[string][]Item `json:"pinned_data,omitempty" yaml:"pinned_data,omitempty"`
}

type DisplayCondition struct {
	Field  string   `json:"field"`
	Equals []string `json:"equals"`
}

type ExpressionEvaluator interface {
	Eval(ctx context.Context, source string, bindings map[string]any) (any, error)
}

type Item map[string]any

type ItemSource struct {
	Node string `json:"node,omitempty"`
	Port string `json:"port,omitempty"`
}

type Node struct {
	ID          string              `json:"id" yaml:"id"`
	Type        string              `json:"type" yaml:"type"`
	Parameters  map[string]any      `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Connections map[string][]string `json:"connections,omitempty" yaml:"connections,omitempty"`
	// RetryOnFail/MaxTries/WaitBetweenTriesMS/OnError (Tier 3.1) are real
	// production behavior - not test/dev overrides like PinnedData - so
	// they're siblings of Parameters/Connections here rather than a
	// separate top-level map, mirroring n8n's own INode shape exactly.
	// RetryOnFail off (the default, and every graph saved before this field
	// existed) means Execute is called exactly once, today's existing
	// behavior. MaxTries is meaningful only when RetryOnFail is true, and
	// clamped 2-5 by the engine; WaitBetweenTriesMS is clamped 0-5000.
	RetryOnFail        bool `json:"retry_on_fail,omitempty" yaml:"retry_on_fail,omitempty"`
	MaxTries           int  `json:"max_tries,omitempty" yaml:"max_tries,omitempty"`
	WaitBetweenTriesMS int  `json:"wait_between_tries_ms,omitempty" yaml:"wait_between_tries_ms,omitempty"`
	// OnError decides what happens once every retry attempt (or the single
	// attempt, if RetryOnFail is off) has failed: "" (unset, the default -
	// today's existing behavior: NodeResult.Success=false, downstream
	// dependents skipped), "continueRegularOutput" (proceed with empty
	// output as if nothing happened), or "continueErrorOutput" (route a
	// single synthesized {"error": message} item onto a new "error" port,
	// letting a downstream branch handle the failure explicitly). Retry and
	// OnError are independent: a node can continue-on-error without ever
	// retrying, or retry a few times and still stop the run.
	OnError string `json:"on_error,omitempty" yaml:"on_error,omitempty"`
	// Tools lists the IDs of other nodes this node (which must be type
	// "query" or "tools" - enforced by Validate) may invoke as LLM-callable
	// tools during its turn, in addition to (never instead of) whatever it's
	// wired to via Connections. A node named here that has no real
	// Connections of its own stays dormant - the engine never schedules it
	// eagerly (see topologicalLevels) - and only runs when the query's LLM
	// actually calls it (see ResolveTools). A node that's both wired into
	// Connections *and* named in some query's Tools keeps running in its
	// normal sequential position too - dual-use, purely additive
	// (automation-app-pages.md §37.9). A target of type "tools" is expanded
	// recursively rather than called directly - see ResolveTools - letting
	// several "query" nodes share the same reusable, individually-toggleable
	// tool group instead of each repeating the same list of IDs.
	Tools []string `json:"tools,omitempty" yaml:"tools,omitempty"`
	// Agent is the ID of the "agent"-type node providing this "query" node's
	// persona - required on every "query" node (enforced by Validate), never
	// set on any other type. A plain ID reference rather than a Connections
	// edge, same reasoning as Tools above: it's a structural relationship
	// ("which identity do I run as"), not data flow, so the referenced agent
	// node is looked up directly rather than needing to run/be scheduled at
	// all.
	Agent string `json:"agent,omitempty" yaml:"agent,omitempty"`
}

type NodeDescription struct {
	Type        string         `json:"type"`
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Category    string         `json:"category"`
	Properties  []NodeProperty `json:"properties,omitempty"`
	// IsTrigger marks a node type that can act as a graph's entry point (has
	// no meaningful input - Run already seeds every node with no
	// predecessors, trigger or not) and carries its own activation config
	// (e.g. a schedule) rather than transforming upstream data. An authoring
	// UI uses this to render trigger nodes distinctly (no input handle,
	// grouped separately) without hardcoding a type-name list.
	IsTrigger bool `json:"isTrigger,omitempty"`
	// IsTestable marks a node type whose executor implements
	// TestableExecutor — an authoring UI uses this to show a "Test
	// connection" affordance without hardcoding a type-name list. Set by
	// Registry.Types() via a type assertion, never by a node's own
	// Description() implementation.
	IsTestable bool `json:"isTestable,omitempty"`
}

type NodeExecutor interface {
	Execute(ctx context.Context, rt *Runtime, input []Item, params map[string]any) (Output, error)
	Description() NodeDescription
	ValidateParameters(params map[string]any) error
}

type NodeProperty struct {
	Name        string               `json:"name"`
	DisplayName string               `json:"displayName"`
	Type        NodePropertyType     `json:"type"`
	Required    bool                 `json:"required,omitempty"`
	Default     any                  `json:"default,omitempty"`
	Placeholder string               `json:"placeholder,omitempty"`
	Description string               `json:"description,omitempty"`
	Options     []NodePropertyOption `json:"options,omitempty"`
	DisplayIf   *DisplayCondition    `json:"displayIf,omitempty"`
}

type NodePropertyOption struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type NodePropertyType string

type NodeResult struct {
	ID      string `json:"id"`
	Type    string `json:"type"`
	Success bool   `json:"success"`
	Skipped bool   `json:"skipped,omitempty"`
	// Pinned is true when this result came from Definition.PinnedData
	// rather than a real Execute call - lets a trace/UI consumer tell
	// "this node actually ran" apart from "this used frozen test data".
	Pinned bool `json:"pinned,omitempty"`
	// Continued is true when this node failed (Success=false) but its own
	// OnError setting (Tier 3.1) let the run proceed anyway rather than
	// stopping - kept distinct from Success so a trace/UI consumer can
	// still tell "this genuinely failed" apart from "this failed but the
	// run kept going", the same distinction n8n's own execution view makes.
	// Run's own downstream-skip/routing logic treats Continued the same as
	// a real success (see engine.go).
	Continued bool `json:"continued,omitempty"`
	// Attempts is how many times Execute was actually called for this node
	// - 1 unless RetryOnFail was set and at least one attempt failed.
	Attempts int `json:"attempts,omitempty"`
	// Input/InputSource are exactly what this node received and, index for
	// index, where each item came from - populated by Run's own scheduling
	// loop (see engine.go), never by the node's own Execute, so every node
	// type gets this for free with no interface change.
	Input       []Item       `json:"input,omitempty"`
	InputSource []ItemSource `json:"input_source,omitempty"`
	// Output is the same single-port view every existing consumer already
	// reads (unchanged) - OutputByPort is the real per-port breakdown Output
	// collapses away (see executeNode).
	Output       []Item            `json:"output,omitempty"`
	OutputByPort map[string][]Item `json:"output_by_port,omitempty"`
	Error        string            `json:"error,omitempty"`
	StartedAt    time.Time         `json:"started_at"`
	EndedAt      time.Time         `json:"ended_at"`
	Duration     time.Duration     `json:"duration"`
}

type Options struct {
	MaxParallel int
}

type Output struct {
	Ports map[string][]Item
}

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

type Result struct {
	Name      string                `json:"name"`
	Success   bool                  `json:"success"`
	StartedAt time.Time             `json:"started_at"`
	EndedAt   time.Time             `json:"ended_at"`
	Duration  time.Duration         `json:"duration"`
	Results   map[string]NodeResult `json:"results"`
	// Order is execution order, in the same level-batched order Run used —
	// mirrors pkg/workflow.Result.Order.
	Order []string `json:"order"`
}

type Runtime struct {
	Secrets     SecretResolver
	Agent       AgentCaller
	Subworkflow SubworkflowRunner
	// Expr enables expression resolution (ResolveParam/ResolveValue) for any
	// node that opts in - nil (the default for a caller that doesn't set it,
	// and for every existing Runtime{} literal/nil Runtime already in use)
	// means expressions are off, not an error; nodes calling ResolveParam
	// against a nil-Expr Runtime just get their literal values back
	// unresolved.
	Expr ExpressionEvaluator
	// Vars is the caller's own organization-scoped named values (Tier 3.2's
	// "Variables"), exposed to expressions as $vars.NAME - see VarsMap.
	// Unlike Secrets, this is a plain map rather than a lazy resolver
	// interface: Variables aren't secret, so the caller resolves the whole
	// set once up front (e.g. before a run starts) instead of one name at a
	// time per access. nil (the default) means no variables are configured,
	// not an error - $vars.ANYTHING then just resolves to undefined.
	Vars map[string]string
	// contains filtered or unexported fields
}

type SecretResolver interface {
	Resolve(ctx context.Context, ref string) (string, error)
}

type SubworkflowRunner interface {
	Run(ctx context.Context, def workflow.Definition) (workflow.Result, error)
}

type TestableExecutor interface {
	TestConnection(ctx context.Context, rt *Runtime, params map[string]any) error
}

type ToolSpec struct {
	// Name is the target node's own ID - stable, unique within the graph,
	// and already meaningful to whoever built it (unlike a synthesized
	// name), so it doubles as the tool's name the LLM sees.
	Name        string
	Description string
	// Schema is a JSON-schema object (the same shape sdk.Tool's
	// InputSchema/schema.FromMap expects: {"type":"object","properties":
	// {...},"required":[...]}), built from the target node's own
	// NodeDescription.Properties.
	Schema map[string]any
	// Invoke runs the target node for real with args overriding its own
	// static Parameters (LLM-supplied keys win), and returns its output
	// serialized as JSON text - the same "records, not a single scalar"
	// shape every other dataflow node produces.
	Invoke func(ctx context.Context, args map[string]any) (string, error)
}