workflow

type AgentReq struct {
	NodeID    string
	AgentID   string
	Prompt    string
	Workspace string
}

type AgentResult struct {
	Text      string
	SessionID string
}

type ApprovalReq struct {
	NodeID    string
	Title     string
	Message   string
	Timeout   time.Duration
	OnTimeout string // "approve" | "reject"
}

type ChannelReq struct {
	NodeID    string
	ChannelID string
	Target    string
	Text      string
}

type Deps struct {
	// RunAgent executes an AI agent node and returns its final text + session id.
	RunAgent func(ctx context.Context, req AgentReq) (AgentResult, error)
	// RunShell executes a shell command node.
	RunShell func(ctx context.Context, req ShellReq) (ShellResult, error)
	// SendEmail delivers an email_send node's message via the caller's SMTP sender
	// (e.g. the org's configured SMTP settings). When nil, email_send nodes error.
	SendEmail func(ctx context.Context, req EmailReq) error
	// SendChannel delivers a send_channel node's message through a configured
	// messaging channel (Slack/Telegram/Discord/WhatsApp). When nil, the node errors.
	SendChannel func(ctx context.Context, req ChannelReq) error
	// RunLLM performs a single, no-tools LLM completion for the llm_prompt node.
	RunLLM func(ctx context.Context, req LLMReq) (string, error)
	// WebSearch / WebFetch back the web node (search the web, fetch a URL as text).
	WebSearch func(ctx context.Context, query string, maxResults int) (string, error)
	WebFetch  func(ctx context.Context, url string) (string, error)
	// KBSearch / KBIngest back the knowledge_base node (vector search / ingest).
	KBSearch func(ctx context.Context, query string, topK int) (string, error)
	KBIngest func(ctx context.Context, req KBIngestReq) (string, error)
	// SQLQuery runs the sql_query node against an external database.
	SQLQuery func(ctx context.Context, req SQLReq) (SQLResult, error)
	// RunSubWorkflow runs another workflow to completion and returns its outputs
	// (sub_workflow node). The caller enforces a recursion-depth guard.
	RunSubWorkflow func(ctx context.Context, workflowID string, payload map[string]any) (map[string]any, error)
	// RequestApproval blocks on a human decision for the approval node.
	RequestApproval func(ctx context.Context, req ApprovalReq) (bool, error)
	// FS performs workspace-confined file operations.
	FS FSOps
	// HTTPClient is used by http_request nodes.
	HTTPClient *http.Client
	// RequestPerm asks the caller to approve a shell command (allow, allowAll).
	RequestPerm func(ctx context.Context, nodeID, command string) (allow, allowAll bool)
	// Emit publishes a run event to the bus (run_started/node_started/... ).
	Emit func(ev map[string]any)
	// PersistNode upserts a node run-state row (executions inspector).
	PersistNode func(ns NodeRunState)
	// Suspend durably records a long-wait suspension so a scheduler can resume the
	// run at resumeAt. When nil, wait nodes fall back to an in-process timer.
	Suspend func(nodeID string, resumeAt time.Time, snap Snapshot)
	// Workspace is the resolved filesystem root for fs/shell nodes.
	Workspace string
	// MaxConcurrency bounds parallel node execution per run (default 8).
	MaxConcurrency int
}

type EmailReq struct {
	NodeID   string
	To       string
	Cc       []string
	Bcc      []string
	Subject  string
	Body     string
	HTML     bool
	FromName string
}

type FSOps interface {
	Read(path string) (string, error)
	Write(path, content string) error
	List(path string) ([]string, error)
	Search(query string) ([]string, error)
}

type FormField struct {
	Name     string `json:"name"`
	Type     string `json:"type,omitempty"`
	Required bool   `json:"required,omitempty"`
}

type KBIngestReq struct {
	NodeID   string
	Name     string
	Content  string // when set, ingest this text directly
	FilePath string // otherwise, ingest a file at this workspace-relative path
}

type LLMReq struct {
	NodeID string
	System string
	Prompt string
}

type NodeResult struct {
	Output         any      // becomes $json for downstream nodes
	FiredPorts     []string // output ports to follow ("" = default)
	AgentSessionID string   // set by agent nodes for inspector deep-linking
	Suspend        bool     // wait node: run suspended, resume scheduled durably
}

type NodeRunState struct {
	RunID          string     `json:"runId"`
	NodeID         string     `json:"nodeId"`
	Status         NodeStatus `json:"status"`
	Input          any        `json:"input,omitempty"`
	Output         any        `json:"output,omitempty"`
	Error          string     `json:"error,omitempty"`
	AgentSessionID string     `json:"agentSessionId,omitempty"`
	Attempts       int        `json:"attempts,omitempty"`
	StartedAt      *time.Time `json:"startedAt,omitempty"`
	CompletedAt    *time.Time `json:"completedAt,omitempty"`
}

type NodeStatus string

type RunOptions struct {
	// TriggerNodeID, when set, seeds only that trigger node (the trigger that
	// started this run). Empty seeds all trigger/indegree-0 nodes.
	TriggerNodeID string
	// StartNodeID begins a partial ("run from here") execution at this node.
	StartNodeID string
	// SingleNode runs only StartNodeID and does not follow its output edges.
	SingleNode bool
	// SeedOutputs pre-populates upstream node outputs (partial execution) so the
	// start node's input can be assembled without re-running upstream nodes.
	SeedOutputs map[string]any
	// SeedVars pre-populates workflow variables (used when resuming a suspended run).
	SeedVars map[string]any
	// Resume marks this as the continuation of a suspended run; the wait node at
	// StartNodeID passes through instead of waiting again.
	Resume bool
	// Test honors the workflow's pinned data: a node with pinned output is not
	// executed; its pinned value is used instead.
	Test bool
}

type RunStatus string

type SQLReq struct {
	NodeID string
	Driver string
	DSN    string
	Query  string
}

type SQLResult struct {
	Rows     []map[string]any
	RowCount int
}

type ShellReq struct {
	NodeID      string
	Command     string
	Cwd         string
	AutoApprove bool
}

type ShellResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

type Snapshot struct {
	Outputs map[string]any `json:"outputs"`
	Vars    map[string]any `json:"vars"`
}

type SwitchCase struct {
	Expression string `json:"expression"`
	Label      string `json:"label,omitempty"`
	PortID     string `json:"portId"`
}

type Workflow struct {
	ID            string         `json:"id"`
	Name          string         `json:"name"`
	Description   string         `json:"description,omitempty"`
	WorkspacePath string         `json:"workspacePath,omitempty"`
	Nodes         []WorkflowNode `json:"nodes"`
	Edges         []WorkflowEdge `json:"edges"`
	Active        bool           `json:"active"`
	Tags          []string       `json:"tags,omitempty"`
	Variables     []WorkflowVar  `json:"variables,omitempty"`
	// PinnedData maps nodeID -> pinned output used during test runs.
	PinnedData map[string]any `json:"pinnedData,omitempty"`
	CreatedAt  time.Time      `json:"createdAt"`
	UpdatedAt  time.Time      `json:"updatedAt"`
}

type WorkflowEdge struct {
	ID           string `json:"id"`
	SourceNodeID string `json:"sourceNodeId"`
	SourcePort   string `json:"sourcePort,omitempty"`
	TargetNodeID string `json:"targetNodeId"`
	TargetPort   string `json:"targetPort,omitempty"`
	Label        string `json:"label,omitempty"`
	Style        string `json:"style,omitempty"`
}

type WorkflowNode struct {
	ID       string             `json:"id"`
	Type     string             `json:"type"`
	Label    string             `json:"label,omitempty"`
	Sublabel string             `json:"sublabel,omitempty"`
	X        float64            `json:"x"`
	Y        float64            `json:"y"`
	Config   WorkflowNodeConfig `json:"config"`
	Disabled bool               `json:"disabled,omitempty"`
}

type WorkflowNodeConfig struct {
	// agent / agent_handoff
	AgentID         string `json:"agentId,omitempty"`
	TaskPrompt      string `json:"taskPrompt,omitempty"`
	WorkspacePath   string `json:"workspacePath,omitempty"`
	WaitForComplete *bool  `json:"waitForCompletion,omitempty"`
	Timeout         int    `json:"timeout,omitempty"`
	// trigger_schedule
	Schedule string `json:"schedule,omitempty"`
	// trigger_webhook
	WebhookPath string `json:"webhookPath,omitempty"`
	// trigger_event
	EventType string `json:"eventType,omitempty"`
	// trigger_form
	FormFields []FormField `json:"formFields,omitempty"`
	// condition
	ConditionExpression string `json:"conditionExpression,omitempty"`
	TrueLabel           string `json:"trueLabel,omitempty"`
	FalseLabel          string `json:"falseLabel,omitempty"`
	// switch
	Cases []SwitchCase `json:"cases,omitempty"`
	// http_request
	URL       string            `json:"url,omitempty"`
	Method    string            `json:"method,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	Body      string            `json:"body,omitempty"`
	AuthType  string            `json:"authType,omitempty"`
	AuthValue string            `json:"authValue,omitempty"`
	// code_transform
	Code     string `json:"code,omitempty"`
	Language string `json:"language,omitempty"`
	// wait
	DelayValue int    `json:"delayValue,omitempty"`
	DelayUnit  string `json:"delayUnit,omitempty"`
	// loop
	IterateOver string `json:"iterateOver,omitempty"`
	LoopVar     string `json:"loopVar,omitempty"`
	// set_variable
	Variables []WorkflowVar `json:"variables,omitempty"`
	// workspace_op
	Operation     string `json:"operation,omitempty"`
	FilePath      string `json:"filePath,omitempty"`
	Content       string `json:"content,omitempty"`
	ContentSource string `json:"contentSource,omitempty"`
	SearchQuery   string `json:"searchQuery,omitempty"`
	// shell_command
	ShellCommand     string `json:"shellCommand,omitempty"`
	ShellCwd         string `json:"shellCwd,omitempty"`
	ShellAutoApprove bool   `json:"shellAutoApprove,omitempty"`
	// email_send (the email body reuses Body / "body" above)
	To        string `json:"to,omitempty"`
	Cc        string `json:"cc,omitempty"`
	Bcc       string `json:"bcc,omitempty"`
	Subject   string `json:"subject,omitempty"`
	EmailHTML bool   `json:"emailHtml,omitempty"`
	FromName  string `json:"fromName,omitempty"`
	// trigger_email (inbound IMAP poll)
	EmailFolder string `json:"emailFolder,omitempty"` // default INBOX
	// send_channel (the message text reuses Body / "body" above)
	ChannelID     string `json:"channelId,omitempty"`     // configured channel to send through
	ChannelTarget string `json:"channelTarget,omitempty"` // chat/channel id, or phone for whatsapp
	// llm_prompt (the user prompt reuses TaskPrompt / "taskPrompt" above)
	SystemPrompt string `json:"systemPrompt,omitempty"`
	LLMJSON      bool   `json:"llmJson,omitempty"` // parse the model's reply as JSON
	// web (operation reuses Operation: "search" | "fetch"; url reuses URL; query reuses SearchQuery)
	MaxResults int `json:"maxResults,omitempty"`
	// knowledge_base (operation reuses Operation: "search" | "ingest";
	//   search: SearchQuery + TopK; ingest file: FilePath; ingest text: Content/ContentSource + KBSourceName)
	TopK         int    `json:"topK,omitempty"`
	KBSourceName string `json:"kbSourceName,omitempty"`
	// sql_query
	SQLDriver string `json:"sqlDriver,omitempty"` // currently: postgres
	SQLDSN    string `json:"sqlDsn,omitempty"`    // connection string / DSN
	SQLQuery  string `json:"sqlQuery,omitempty"`
	// filter (keep the array items for which FilterExpression is truthy)
	FilterExpression string `json:"filterExpression,omitempty"`
	// template (render a {{ }} template; optionally wrap the result under TemplateField)
	Template      string `json:"template,omitempty"`
	TemplateField string `json:"templateField,omitempty"`
	// approval (human-in-the-loop gate)
	ApprovalTitle     string `json:"approvalTitle,omitempty"`
	ApprovalMessage   string `json:"approvalMessage,omitempty"`
	ApprovalTimeout   int    `json:"approvalTimeout,omitempty"`   // minutes; 0 = default 60
	ApprovalOnTimeout string `json:"approvalOnTimeout,omitempty"` // "approve" | "reject" (default reject)
	// sub_workflow
	SubWorkflowID string `json:"subWorkflowId,omitempty"`
	// error handling (all executable nodes)
	OnError      string `json:"onError,omitempty"` // stop|continue|retry (default stop)
	RetryCount   int    `json:"retryCount,omitempty"`
	RetryDelayMs int    `json:"retryDelayMs,omitempty"`
	// output binding
	OutputVar string `json:"outputVar,omitempty"`
}

type WorkflowRun struct {
	ID             string         `json:"id"`
	WorkflowID     string         `json:"workflowId"`
	Status         RunStatus      `json:"status"`
	TriggerType    string         `json:"triggerType"`
	TriggerPayload map[string]any `json:"triggerPayload,omitempty"`
	Error          string         `json:"error,omitempty"`
	StartedAt      time.Time      `json:"startedAt"`
	CompletedAt    *time.Time     `json:"completedAt,omitempty"`
	NodeStates     []NodeRunState `json:"nodeStates,omitempty"`
}

type WorkflowVar struct {
	Name        string `json:"name"`
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
}