Skip to content

FlowDrop Session

Session and message entities for managing interactive, multi-turn workflow execution.

Overview

The flowdrop_session module provides the entity layer for interactive workflow sessions. A session represents an isolated execution environment for a workflow, and session messages track the conversation-like exchange between the user and the workflow.

This module is the foundation for interactive features like the playground and supports multi-turn workflows where the user sends input and the workflow responds over multiple exchanges. It includes a deferred message processor that handles workflow execution after the HTTP response is sent, keeping the UI responsive.

Dependencies

Configuration

Permissions

Permission Description
administer flowdrop_session Full administrative access to sessions. Restricted.
create flowdrop_session Create new sessions
view own flowdrop_session View own sessions
view any flowdrop_session View any session
edit own flowdrop_session Edit own sessions
edit any flowdrop_session Edit any session
delete own flowdrop_session Delete own sessions
delete any flowdrop_session Delete any session
view own flowdrop_session_message View own session messages
view any flowdrop_session_message View any session message
execute session workflow Execute workflows within a session context

Running a turn needs execute session workflow and write (update) access to the session, not just view access: a turn writes to the conversation and runs under the session owner's identity, including the owner's user-scoped memory. Owners always hold update on their own session — edit own flowdrop_session is not required for that — while a non-owner needs edit any flowdrop_session. view any flowdrop_session is an observer permission and never drives a session. Anonymous (uid 0) is never treated as an owner.

Tips and Tricks

Session Lifecycle

  1. Created — A new session is created for a specific workflow
  2. Idle — Session is waiting for user input
  3. Processing — A message has been sent and the workflow is executing
  4. Completed — The session has finished (workflow reached a terminal state)

Deferred Message Processing

The DeferredMessageProcessor service handles workflow execution after the HTTP response is sent. This means the user sees an immediate response while the workflow runs in the background. Message status can be polled via the API.

Queue-Based Processing

For heavier workloads, the module includes a SessionMessageWorker queue worker that processes session messages from a Drupal queue, enabling reliable background processing.

Developer API

All PHP classes in this module are @internal and not part of the stable public API. They may change without notice in any release. See the BC Policy for details.

Services

Service ID Class Description
flowdrop_session.room_repository (alias RoomRepositoryInterface) RoomRepository Creates, loads, finds and deletes sessions
flowdrop_session.room_writer (alias RoomWriterInterface) RoomWriter post(session, MessageDraft): the only way a message row is written
flowdrop_session.room_reader (alias RoomReaderInterface) RoomReader read()/count() with a bounded MessageQuery
flowdrop_session.run_control (alias SessionRunControlInterface) SessionRunControl Stops a session's run, resets a stuck session; changes state and announces it (SessionStoppedEvent, SessionResetEvent), writes no row
flowdrop_session.tool_artifact_parking (alias ToolArtifactParkingInterface) ToolArtifactParking Parks a run's tool artifacts across a pause
flowdrop_session.api_normalizer (alias SessionApiNormalizer) SessionApiNormalizer The session and message rows of the HTTP wire
flowdrop_session.turn_service (alias SessionTurnServiceInterface) SessionTurnService The chat-turn verb
flowdrop_session.service SessionService Deprecated in 2.7.0, removed in 3.0: a facade over the services above
flowdrop_session.deferred_message_processor DeferredMessageProcessor Processes workflow execution after HTTP response

Events and reporting rows

The module runs turns and changes state; it writes no reporting rows into the room, and no failure rows (#3592467). It announces what happened instead: the turn events (SessionTurnStartedEvent, SessionTurnCompletedEvent), the companion SessionTurnResultsEvent on every stop (nested runs and resumes included, with the declared outputs and the executing workflow), SessionStoppedEvent, SessionResetEvent and SessionTurnFailedEvent (cron timeout, a resume that threw, a stuck session cron released). The Playground posts its notices, job logs, run outcome rows and "Execution failed" rows on them; persist_job_logs and notice_level filter all but the failure rows. Nothing in this module needs the Playground: without it a session holds only what people and the workflow wrote, failures included, and a client reads a failure from TurnResult, the events or the pipeline's status. See Session Turns & Events.

Entities

FlowDropSession (Content Entity)

Represents an isolated execution environment for a workflow. Tracks the session state, associated workflow, and ownership.

FlowDropSessionMessage (Content Entity)

Messages within a session — both user inputs and workflow responses.

References