engine

type DependencyDeclarer ¶

type DependencyDeclarer interface {
	Dependencies(n workflow.Node) []NodeDependency
}

DependencyDeclarer is implemented by executors that want to surface their per-node dependencies through workflow_describe.

Called once per Node when describing a workflow; the implementation inspects n.<fields> to decide what the node actually touches. Return nil for nodes whose runtime is pure / has no external dep.

type Describer ¶

type Describer interface {
	Descriptor() NodeDescriptor
}

Describer is implemented by executors that want to expose schema + docs to the MCP catalog. Optional — executor that does not implement gets a bare descriptor with no schema.

type Engine ¶

type Engine struct {
	Layout      config.Layout
	Service     service.Service
	StateStore  state.Store
	Executors   map[workflow.NodeType]workflow.Executor
	Descriptors map[workflow.NodeType]NodeDescriptor
	// Triggers carries the per-trigger-type descriptors (schema + docs).
	// MCP `workflow_node_detail` resolves `trigger:<type>` against this
	// registry. Seeded by setup; zero value = no triggers discoverable.
	Triggers *TriggerRegistry
	Now      func() time.Time
	IDGen    func() string
	// OnEvent is the legacy single-slot broadcast hook (SSE owns it).
	// Newer subscribers should use Engine.Subscribe — that registers
	// against a fan-out broker. Both fire per event; legacy first,
	// broker second.
	OnEvent func(id, runID string, ev workflow.RunEvent)
	// contains filtered or unexported fields
}

func New(layout config.Layout, svc service.Service, ss state.Store) *Engine

func (e *Engine) PublishForTest(id, runID string, ev workflow.RunEvent)

func (e *Engine) Register(t workflow.NodeType, ex workflow.Executor)

func (e *Engine) RegisterWithDesc(t workflow.NodeType, ex workflow.Executor, desc NodeDescriptor)

func (e *Engine) Run(ctx context.Context, w workflow.Workflow, evt workflow.Event) (workflow.RunState, error)

func (e *Engine) SetEventHook(fn func(id, runID string, ev workflow.RunEvent))

func (e *Engine) Subscribe(bufferSize int) *Subscription

type NodeDependency ¶

type NodeDependency struct {
	Kind    string         `json:"kind"`
	Ref     string         `json:"ref"`
	Details map[string]any `json:"details,omitempty"`
}

NodeDependency is one external surface a node touches at runtime. Kind is a short tag the consumer uses to bucket entries; Ref is the human-readable identifier (channel name, connector module.op pair, provider name, sheet ID, …). Optional Details map carries kind-specific extras the consumer may want — keep it small.

type NodeDescriptor ¶

type NodeDescriptor struct {
	Type        workflow.NodeType
	Description string
	WhenToUse   string
	Example     string
	Schema      map[string]any    // reflected from per-node schema struct
	Output      map[string]string // field → description
	wickdocs.Docs
}

Engine walks a workflow graph and dispatches each node to its Executor. Caller wires concrete executors via Register; the engine stays decoupled from individual node impls.

OnEvent is an optional broadcast hook fired after every event hits the StateStore. The UI subscribes via SSE to paint per-node progress without polling state.json. Set via SetEventHook so existing callers stay source-compatible. NodeDescriptor bundles the schema + docs for a node type. Populated via RegisterWithDesc — single source of truth lives in the executor file itself (nodes/<type>.go Descriptor method).

Docs carries the opt-in self-documentation contract (quirks, examples, templateable fields, pair-with, common pitfalls) projected by the MCP `workflow_node_detail` op. Zero-value Docs = current behaviour; populate per executor when worth it. See internal/agents/workflow/docs and internal/docs/workflow/24-describe-contract.md.

type SubEvent ¶

type SubEvent struct {
	WorkflowID string
	RunID      string
	Event      workflow.RunEvent
}

SubEvent is the payload one subscriber receives.

type Subscription ¶

type Subscription struct {
	Ch chan SubEvent
	// contains filtered or unexported fields
}

Subscription is the per-call subscription handle returned by Engine.Subscribe. Call Cancel() to unregister; safe to call multiple times. Receive events via the Ch channel — buffered to avoid losing events on routine producers, but bounded so a stalled subscriber doesn't pile memory.

func (s *Subscription) Cancel()

type TemplateableFieldsDeclarer ¶

type TemplateableFieldsDeclarer interface {
	TemplateableFields(n workflow.Node) map[string]string
}

TemplateableFieldsDeclarer is implemented by executors whose node type carries templateable strings on fields beyond the common pool scanned by default (Prompt, PromptFile, URL, Body, Expr, Input, Expression, SQL).

Return name → value pairs for each templateable string field present on this node so the cross-ref scan in workflow_describe can find {{.Node.X}} references on custom fields. The `name` is the field label surfaced in the issue path (e.g. "code", "sheet_range") — pick labels that match the wick:"key=..." tag for the field when one exists.

type TriggerDescriptor ¶

type TriggerDescriptor struct {
	Type        workflow.TriggerType
	Description string
	Schema      map[string]any
	Example     string
	wickdocs.Docs
}

TriggerDescriptor bundles the schema + docs for a trigger type (cron / channel / webhook / manual / schedule_at / error). One descriptor per workflow.TriggerType — the MCP `workflow_node_detail` op resolves a `trigger:<type>` key to this struct and projects it to the unified detail response.

Schema is a JSON-Schema-ish map of the fields a trigger entry carries on workflow.Trigger; Example is a copy-pasteable YAML block. Docs is the opt-in self-documentation bundle (examples, quirks, templateable fields, pair-with, common pitfalls).

Unlike NodeDescriptor (auto-populated by Engine.Register from the executor's Describer method), TriggerDescriptor is hand-registered at setup time because triggers don't have executors — they're dispatch keys handled by the router. The default catalog lives in engine.DefaultTriggerDescriptors() so callers can choose between registering the canonical set or overriding individual entries.

func DefaultTriggerDescriptors() []TriggerDescriptor

type TriggerRegistry ¶

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

TriggerRegistry holds every TriggerDescriptor wired into one engine. Concurrent-safe — registration happens at boot, reads happen for every MCP discovery call.

func NewTriggerRegistry() *TriggerRegistry

func (r *TriggerRegistry) Get(t workflow.TriggerType) (TriggerDescriptor, bool)

func (r *TriggerRegistry) List() []TriggerDescriptor

func (r *TriggerRegistry) Register(d TriggerDescriptor)

func (r *TriggerRegistry) RegisterMany(ds ...TriggerDescriptor)