workflow_name: Top-level identifier.
triggers: A list defining how a workflow execution starts.
    Each trigger has a type (webhook, schedule, etc.).
    Webhook triggers define provider and webhook_id (matching the URL).
    Crucially, each trigger specifies a target_taskflow ID, linking it to a specific task sequence within the same file.
    input_mapping (optional) could explicitly define how data from the trigger event (e.g., webhook payload) becomes the ${INPUT} for the target taskflow.
taskflows: A list defining the actual execution logic (the processes).
    Each item has a taskflow_id referenced by triggers.
    Contains the familiar tasks, subflows, and conditions structure.
    Tasks can access initial data via ${INPUT.<field_name>}.

workflow_name (string, Required): A unique identifier for this workflow definition file. Used for referencing and management.
description (string, Optional): A human-readable explanation of the workflow's overall purpose.
version (string, Optional): Version string for this workflow definition (e.g., "1.0.0").
triggers (list, Optional): Defines the events or conditions that initiate the execution of specific taskflows within this file. See Trigger Definition.
taskflows (list, Required): Defines the actual sequences of operations (tasks, subflows, conditions). See Taskflow Definition.
global_configs (object, Optional): A section for defining configurations shared across the workflow, such as secret references. See Global Configurations.

    config:
      cron_expression: string # Required. Standard cron format (e.g., "0 * * * *")

    (Define config structures for other types as needed)
target_taskflow (string, Required): The taskflow_id (from the taskflows section in this file) that should be executed when this trigger fires.
input_mapping (object, Optional): Defines how data from the trigger event is mapped to the ${INPUT} context of the target_taskflow. If omitted, the entire trigger payload might be passed as ${INPUT} by default.
    Keys are the field names within the ${INPUT} context (e.g., taskflow_input_field).
    Values can be:
        Literal values (string, number, boolean).
        Expressions referencing the trigger's payload (e.g., "${TRIGGER.payload.some_field}"). The exact syntax (${TRIGGER...}) needs standardization.

secrets (object, Optional): A map for defining references to secrets (e.g., API keys, webhook secrets). The values might be direct strings or use a specific syntax (like lookup_from_vault:...) indicating how the SLOP system should retrieve the actual secret value securely at runtime. Trigger configurations (secret_ref) and potentially task configurations could reference these keys.

workflow_name: "UnipileEmailProcessingWorkflow"
description: "Handles incoming emails from Unipile via webhook."
version: "1.2" # Incremented version

global_configs:
  secrets:
    unipile_secret: "lookup:vault/slop/unipile_webhook_secret"

triggers:
  - id: "unipile_new_email_webhook"
    type: "webhook"
    enabled: true
    config:
      provider: "unipile"
      webhook_id: "new_email"
      secret_ref: "unipile_secret"
      expected_payload_schema:
        type: object
        properties:
          resource_id: { type: string }
          thread_id: { type: string }
        required: [resource_id, thread_id]
    target_taskflow: "process_email_sequence"
    input_mapping:
      email_resource_id: "TRIGGER.payload.resource_id"
      email_thread_id: "TRIGGER.payload.thread_id"

taskflows:
  - taskflow_id: "process_email_sequence"
    description: "Fetches, analyzes, and tags an email."
    input_schema:
      type: object
      properties:
        email_resource_id: { type: string }
        email_thread_id: { type: string }
      required: [email_resource_id, email_thread_id]
    tasks:
      - id: "get_email_content"
        name: "Get Email Resource Content"
        type: "mfo_api_resource_get"
        config:
          resource_id: "INPUT.email_resource_id"
        successors: ["analyze_email"]
        outputs:
          - get_email_content.resource

      - id: "analyze_email"
        name: "Analyze Email with LLM (using Template)"
        type: "mfo_api_chat_send" # Or potentially a dedicated "prompt_template_task"
        config:
          prompt_template_id: "email_analysis_v1" # ID referencing an external prompt template
          prompt_context:
            email_content: "get_email_content.resource.content"
          provider_id: "default_llm"
        dependencies: ["get_email_content"]
        successors: ["tag_email_thread"]
        outputs:
          - analyze_email.analysis_result # e.g., { "sender": "...", "subject": "...", "summary": "..." }

      - id: "tag_email_thread"
        name: "Tag Email Thread via Tool"
        type: "mfo_api_tool_execute"
        config:
          tool_id: "unipile_email_tag_thread"
          arguments:
            tag_name: "ai_analyzed"
            thread_id: "INPUT.email_thread_id"
        dependencies: ["analyze_email"]

### Example 2: Scheduled Daily Report (Content Generation Abstracted)

```yaml
workflow_name: "DailyReportingWorkflow"
description: "Generates and distributes a daily sales report."
version: "1.1" # Incremented version

triggers:
  - id: "daily_midnight_schedule"
    type: "schedule"
    enabled: true
    config:
      cron_expression: "0 0 * * *"
    target_taskflow: "generate_and_send_report"

taskflows:
  - taskflow_id: "generate_and_send_report"
    description: "Generates a sales report and emails it."
    tasks:
      - id: "fetch_sales_data"
        name: "Fetch Sales Data"
        type: "mfo_api_tool_execute"
        config:
          tool_id: "internal_db_query_sales"
          arguments:
            period: "last_day"
        successors: ["format_report"]
        outputs:
          - fetch_sales_data.sales_figures

      - id: "format_report"
        name: "Format Sales Report"
        type: "custom_report_formatter"
        config:
          data: "fetch_sales_data.sales_figures"
          template: "daily_sales_template.md"
        dependencies: ["fetch_sales_data"]
        successors: ["generate_subject"]
        outputs:
          - format_report.report_content

      - id: "generate_subject"
        name: "Generate Report Subject"
        type: "simple_template_task" # Example: A task using a simple template
        config:
          template_string: "Daily Sales Report - SYSTEM.DATE"
          # Alternatively, use an LLM call:
          # type: "mfo_api_chat_send"
          # config:
          #   prompt_template_id: "daily_report_subject_v1"
          #   prompt_context: { report_date: "SYSTEM.DATE" }
          #   provider_id: "fast_llm"
        dependencies: ["format_report"]
        successors: ["email_report"]
        outputs:
          - generate_subject.subject_text

      - id: "email_report"
        name: "Email Sales Report"
        type: "mfo_api_tool_execute"
        config:
          tool_id: "send_email"
          arguments:
            to: "management@example.com"
            subject: "generate_subject.subject_text"
            body: "format_report.report_content"
        dependencies: ["generate_subject", "format_report"]

YAML Parsing:
    Current: The system (likely slop-client or a server component loading taskflows for jobs) parses YAML expecting only the taskflow definition (name, tasks, subflows, conditions).
    Unified: A new or modified parser would be needed to understand the top-level workflow_name, triggers, taskflows, and global_configs structure.
Trigger Management (Server-Side Focus Recommended):
    Current: Triggers are managed explicitly via the /api/config/event-triggers endpoints on the server. Webhook requests hit /webhooks/:provider/:webhook_id, a specific handler publishes to an event channel, and a configured EventJobTrigger listening on that channel creates a job (POST /api/jobs).
    Unified: The SLOP server would likely take primary responsibility for processing the triggers section of the unified YAML.
        Loading: The server needs a mechanism to load/register these unified workflow YAML files.
        Webhook Triggers: When loading a YAML with a webhook trigger, the server would need to:
            Ensure its internal routing is configured to handle requests for the specified /webhooks/:provider/:webhook_id.
            Associate that incoming route directly with the target_taskflow defined in the same YAML file.
            Handle security verification using the secret_ref (looking up the secret via global_configs).
            This could potentially replace the need for the separate /api/config/event-triggers database table and API for webhook-based triggers defined in this unified format. The YAML itself becomes the source of truth for the trigger configuration.
        Schedule Triggers: When loading a YAML with a schedule trigger, the server would need to interact with its internal scheduling system to register a job that runs the target_taskflow according to the cron_expression.
Taskflow Initiation and Input Mapping:
    Current: A job (/api/jobs) is created with a job_process_id (taskflow name) and an input payload. The taskflow executor uses this.
    Unified: When a trigger defined in the unified YAML fires (e.g., a matching webhook arrives or a schedule hits):
        The server identifies the target_taskflow from the YAML.
        It processes the input_mapping (if present) using data from the trigger event (e.g., webhook payload, current time for schedule) to construct the initial ${INPUT} context.
        It then initiates the execution of that specific target_taskflow (likely still using its internal job/taskflow execution engine), providing the constructed ${INPUT} context.
Role of slop-client:
    The slop-client's core taskflow execution logic (internal/taskflow interpreting tasks, subflows, conditions, handling ${task_id.output_key}, calling SLOP API tasks) would remain largely relevant if the server still delegates the actual execution of the taskflow steps to a client-like worker.
    However, the client might become less involved in defining or triggering the workflow if the unified YAML is primarily managed and interpreted by the server.
    The client might still be used for manually running taskflows defined in these YAMLs (bypassing the triggers section) or for interacting with the server for other purposes.

Requires a new YAML parser on the server (or wherever these files are processed).
Requires server-side logic to interpret the triggers section and configure internal routing/scheduling.
Potentially simplifies or replaces the existing /api/config/event-triggers system for workflows defined in the unified format.
Requires a mechanism on the server to map trigger events and input_mapping to the initiation of the correct target_taskflow with the right input context.
The core go-taskflow execution logic for tasks/subflows/conditions remains similar, but the overall orchestration layer changes.

Example 1 (Webhook): Showed a workflow_name: UnipileEmailProcessingWorkflow with a webhook trigger for unipile/new_email targeting a taskflow_id: process_email_sequence. Included global_configs for the secret, input_mapping, and the taskflow definition accessing ${INPUT.email_resource_id} and ${INPUT.email_thread_id}.
Example 2 (Schedule): Showed a workflow_name: DailyReportingWorkflow with a schedule trigger (cron_expression: "0 0 * * *") targeting taskflow_id: generate_and_send_report. The taskflow fetched data, formatted it, and emailed it.

This unified structure requires changes to the SLOP server to parse the new format.
The server would manage triggers defined in the YAML, potentially replacing the need for the separate /api/config/event-triggers API for these workflows.
The server would handle routing webhooks or schedules to the correct target_taskflow defined in the same file.
The server would manage input_mapping to provide the correct ${INPUT} context to the taskflow.
The core task execution logic within slop-client (or a server-side worker) remains relevant for running the actual tasks, subflows, and conditions.

workflow_name: "ExampleWorkflow"
# ... triggers section (if any) ...

taskflows:
  - taskflow_id: "main_process"
    description: "The primary sequence of operations."
    tasks: 
      # Task definitions go here
    subflows: 
      # Subflow definitions go here (optional)
    conditions:
      # Condition definitions go here (optional)

# ... other taskflows ...

workflow_name: "SequentialDataPassingExample"
version: "1.0"

taskflows:
  - taskflow_id: "sequential_flow"
    description: "Demonstrates passing data between two sequential tasks."
    tasks:
      - id: "extract_initial_data"
        name: "Extract User Info"
        type: "custom_data_extractor" # Assumes a custom task type exists
        config:
          source_file: "/path/to/input.json"
        # This task is assumed to produce an output map like: {"user_id": "usr_123", "email": "test@example.com"}
        outputs: # Documenting expected outputs is good practice
          - extract_initial_data.user_id
          - extract_initial_data.email
        successors: ["send_welcome_email"]

      - id: "send_welcome_email"
        name: "Send Welcome Email via Tool"
        type: "slop_tool_call" # Using the generic tool caller
        config:
          tool_id: "email_sender_tool" # The ID of the SLOP Server tool
          arguments:
            recipient_email: "${extract_initial_data.email}" # Reference output from the previous task
            subject: "Welcome!"
            body_template: "welcome_template.txt"
            user_identifier: "${extract_initial_data.user_id}" # Reference another output
        dependencies: ["extract_initial_data"] # Explicitly depends on the first task

workflow_name: "ParallelProcessingExample"
version: "1.0"

taskflows:
  - taskflow_id: "parallel_flow"
    description: "Demonstrates parallel execution and result aggregation."
    tasks:
      - id: "start_node" # Dummy node to start parallel branches
        type: "no_op" # A task that does nothing, just for structure
        successors: ["process_region_a", "process_region_b"]

      - id: "process_region_a"
        name: "Process Data for Region A"
        type: "slop_tool_call"
        config:
          tool_id: "region_processor"
          arguments:
            region: "A"
        # Assumed output: {"processed_count": 150}
        outputs: ["process_region_a.processed_count"]
        dependencies: ["start_node"]
        successors: ["aggregate_results"]

      - id: "process_region_b"
        name: "Process Data for Region B"
        type: "slop_tool_call"
        config:
          tool_id: "region_processor"
          arguments:
            region: "B"
        # Assumed output: {"processed_count": 210}
        outputs: ["process_region_b.processed_count"]
        dependencies: ["start_node"]
        successors: ["aggregate_results"]

      - id: "aggregate_results"
        name: "Aggregate Regional Results"
        type: "custom_aggregator" # Assumes a custom task type exists
        config:
          # This custom task's implementation needs to know how to find 
          # and sum the outputs from the preceding parallel tasks.
          # Option 1: Explicitly list inputs (less flexible if branches change)
          # input_counts: [
          #   "${process_region_a.processed_count}",
          #   "${process_region_b.processed_count}"
          # ]
          # Option 2: Task logic queries context for outputs from dependencies
          aggregation_source_tasks: ["process_region_a", "process_region_b"]
        # Assumed output: {"total_count": 360}
        outputs: ["aggregate_results.total_count"]
        dependencies: ["process_region_a", "process_region_b"] # Depends on both parallel tasks

workflow_name: "ConditionalBranchingExample"
version: "1.0"

taskflows:
  - taskflow_id: "conditional_flow"
    description: "Demonstrates conditional execution path."
    tasks:
      - id: "check_order_value"
        name: "Check Order Value"
        type: "slop_tool_call"
        config:
          tool_id: "order_service_get_value"
          arguments:
            order_id: "${INPUT.order_id}" # Assuming order_id comes from trigger input
        # Assumed output: {"value": 150.75}
        outputs: ["check_order_value.value"]
        successors: ["value_condition"]

      - id: "process_high_value_order"
        name: "Process High Value Order"
        type: "slop_tool_call"
        config:
          tool_id: "high_value_processor"
          arguments:
            order_id: "${INPUT.order_id}"
            value: "${check_order_value.value}"
        dependencies: ["value_condition"] # Depends on the condition outcome

      - id: "process_standard_order"
        name: "Process Standard Order"
        type: "slop_tool_call"
        config:
          tool_id: "standard_processor"
          arguments:
            order_id: "${INPUT.order_id}"
        dependencies: ["value_condition"] # Depends on the condition outcome

    conditions:
      - id: "value_condition"
        name: "Is Order Value > 100?"
        type: "simple_threshold_evaluator" # Assumes a custom condition evaluator type
        config:
          input_value: "${check_order_value.value}" # Get value from the previous task
          threshold: 100
          operator: ">" # Specify comparison operator
        dependencies: ["check_order_value"]
        # Successors list maps evaluator result index to next task ID
        successors:
          # Index 0: Condition is false (value <= 100)
          - "process_standard_order" 
          # Index 1: Condition is true (value > 100)
          - "process_high_value_order"