Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Events, CQRS and Observability

Domain Events

DomainEvent (Orkeon.Domain.SharedKernel.Events) is the abstract base record of every domain event: Id (DomainEventId), OccurredAt (UTC), EventName (the type name) and Version (virtual, 1 by default, for serialization compatibility).

Aggregates (AggregateRoot<TEntityId>, which implements IHasDomainEvents) queue events with the protected RaiseDomainEvent(); DomainEvents exposes the pending ones and ClearDomainEvents() empties the list.

Dispatch

Dispatch goes through IDomainEventDispatcher (Domain), implemented by DomainEventDispatcher (Orkeon.Infrastructure.DomainEvents, scoped, registered by AddOrkeonInfrastructure()): for each event it resolves every IDomainEventHandler<TEvent> registered in DI, from the caller's scope, and awaits its HandleAsync, in order (DispatchAsync, DispatchManyAsync); an event without a handler is logged at Debug level.

Events are dispatched at three points.

As a run goes. Every orchestration mode moves the tasks it runs and their agents through their lifecycle. The rule lives in one place, the outcome the six modes share (CrewRunOutcome, which drives TaskLifecycle): it applies one transition of the task and of the agents concerned, saves them in their repositories β€” the run's scoped ones β€”, then dispatches their queued events, the task's first. A handler therefore hears of a task while the run goes, before the crew's own events. For a task that runs:

  1. TaskAssignedEvent when the run gives it to another agent than the one it carries β€” a task that names no agent, the agent a hierarchical or autonomous manager picks β€”, and AgentAssignedToTaskEvent the first time an agent is given it;
  2. TaskStatusChangedEvent (Pending β†’ InProgress) and TaskStartedEvent, then AgentStartedTaskEvent;
  3. when it ends, TaskStatusChangedEvent and TaskCompletedEvent (its output and the agent that produced it), then AgentCompletedTaskEvent β€” or TaskFailedEvent and AgentFailedTaskEvent, with the cause.

A task's construction events (TaskCreatedEvent, the TaskAssignedEvent of a declared agent:, TaskDependenciesUpdatedEvent) are still queued when its run first moves it, and go out then, like an agent's (AgentCreatedEvent, AgentCapabilitiesUpdatedEvent). What each mode adds:

Mode Lifecycle
Sequential One start, one end per task, in the run's order.
Parallel Each task of a wave starts as it is launched; the wave's tasks end once it has joined, in declaration order. An agent given two tasks of a wave runs both at once (Agent.CurrentTasks).
Graph A task starts once and keeps running through its retries, under the agent it was given; it ends when it succeeds or gives up.
Hierarchical The agent the manager assigns starts the task β€” re-assigned to it when the crew declared another. Its revisions are part of its work: it ends the task once, completed when the manager accepted an output, failed otherwise. A task the manager gives to an agent the crew does not carry fails without starting.
Consensual The task starts once, under no single agent (TaskStartedEvent.AgentId is null). Every agent that answers starts it too and ends it with its own last answer (AgentCompletedTaskEvent) or its error (AgentFailedTaskEvent); the task is then assigned to the author of the retained answer and completes under it.
Autonomous The agent that claims a task starts it. When it fails and the task goes to a peer, it fails the task (AgentFailedTaskEvent, with its error), the task is assigned to the peer (TaskAssignedEvent), who starts it and ends it: the task started once, and ends under the peer.

A task that does not run is cancelled with its reason (TaskCancelledEvent): skipped because a task it depends on did not succeed (skipped: it depends on task …, which did not succeed) β€” never started, never ended, its StartedAt and CompletedAt empty β€”, or never reached by an Autonomous run whose budget ran out (not executed: …). A task an interruption catches running is cancelled when the run was cancelled (the run was cancelled) and failed when it stopped on an exception or a graph circuit break (the run stopped: …); the agents running it fail it with the same reason.

After the run, the repository holds what happened: a task is Completed with its output, StartedAt and CompletedAt, Failed with StartedAt and CompletedAt (when it ended), or Cancelled. A crew kicked off again without being reloaded β€” the C# KickoffAsync loop, the fixed-crew CrewAgent β€” reopens each task the first time the new run moves it (CrewTask.Reopen: back to Pending with a TaskStatusChangedEvent, its output and dates cleared, its assignment kept).

Bookkeeping never changes a run: a transition the aggregate refuses is logged as a warning and the run goes on; a handler that throws is logged and the events after it still go out β€” the same rule as the crew's. Saving and dispatching ignore the run's token, so a cancelled run still says what became of its tasks. A strategy built by hand without an IDomainEventDispatcher (the optional domainEvents dependency, which the container always fills) moves and saves its tasks and leaves their events queued.

At the end of a crew kickoff. SequentialCrewOrchestrator (the ICrewOrchestrationService) dispatches the crew's queued events once the run ends β€” on success, failure and cancellation alike β€” and then empties the aggregate, so a second kickoff never dispatches them again. KickoffForEachAsync (one run per input, in sequence), KickoffNoWaitAsync and KickoffStreamingAsync go through the same point β€” a streamed kickoff is the same run. A kickoff therefore delivers, in order, the events queued while the crew was built (CrewCreatedEvent, AgentJoinedCrewEvent, TaskAddedToCrewEvent, on the first run), then CrewExecutionStartedEvent, then CrewExecutionCompletedEvent or CrewExecutionFailedEvent β€” one terminal transition per run. A run whose every task succeeded completes the crew (CrewExecutionCompletedEvent.CompletedTasks counts each task once, by its final outcome: a task a graph retried before it succeeded is one completed task). A run with a task that failed or was skipped fails it, like the CrewOutput and the exit code: CrewExecutionFailedEvent with the crew's error as its Reason (each failed or skipped task named) and no Exception, the crew and its execution left Failed. A run that stopped on an exception fails with it as the Exception; a cancelled run is a failed run whose Exception is the OperationCanceledException β€” the run event stream says crew_cancelled, the domain has no cancelled transition. A handler that throws is logged and skipped: it changes neither the run's CrewOutput nor the error it reports, and the events after it are still delivered. The orchestrator calls the dispatcher directly rather than a unit of work, whose single tracked aggregate would lose the crew.

When a unit of work is saved (the CQRS commands):

  1. The in-memory repositories call IUnitOfWork.Track(aggregate) on every add/update. InMemoryUnitOfWork keeps one aggregate per scope (the last tracked one β€” one command, one aggregate).
  2. IUnitOfWork.SaveChangesAsync() runs the persist step (empty for the in-memory adapter), dispatches the tracked aggregate's pending events, then clears them β€” even when a handler throws.
  3. SaveChangesAsync() is called by UnitOfWorkCommandHandler, the decorator wrapped around every CQRS command handler (see below).

Handlers

AddOrkeonApplication() scans the Orkeon.Application assembly and registers every IDomainEventHandler<T> it finds (scoped). Four ship, all of them structured-logging handlers: AgentCompletedTaskHandler and AgentFailedTaskHandler (Information and Warning, as a run goes), CrewExecutionCompletedHandler, CrewExecutionFailedHandler. A handler in another assembly is registered explicitly: services.AddScoped<IDomainEventHandler<TaskCompletedEvent>, MyHandler>().

The 23 domain events

Family Events Raised by
Agent (6) AgentCreatedEvent, AgentAssignedToTaskEvent, AgentStartedTaskEvent, AgentCompletedTaskEvent, AgentFailedTaskEvent, AgentCapabilitiesUpdatedEvent Agent aggregate
Crew (6) CrewCreatedEvent, AgentJoinedCrewEvent, TaskAddedToCrewEvent, CrewExecutionStartedEvent, CrewExecutionCompletedEvent, CrewExecutionFailedEvent Crew aggregate
Task (8) TaskCreatedEvent, TaskAssignedEvent, TaskStatusChangedEvent, TaskStartedEvent, TaskCompletedEvent, TaskFailedEvent, TaskCancelledEvent, TaskDependenciesUpdatedEvent CrewTaskBase<TContext> aggregate (CrewTask)
Memory (3) MemoryStoreCreatedEvent, MemoryAddedEvent, MemoryPromotedEvent AgentMemoryStore aggregate

Total: 23 domain events, each raised by a method of its aggregate. The event records live next to their aggregate (Agent/Events/, Crew/Events/, Task/Events/, Memory/Events/).

CQRS and pipeline

The Application layer implements CQRS with ICommand<TResponse> / ICommandHandler<TCommand, TResponse> and IQuery<TResponse> / IQueryHandler<TQuery, TResponse> (Orkeon.Application.Common.CQRS), plus ICommandValidator<TCommand> (Orkeon.Application.Validation). AddOrkeonApplication() scans the Application assembly and registers them; there is no mediator β€” resolve the handler interface from DI and call HandleAsync.

Each command handler is registered behind two decorators:

ValidatingCommandHandler   (only when a validator exists β€” throws CommandValidationException)
  └── UnitOfWorkCommandHandler   (IUnitOfWork.SaveChangesAsync β†’ domain events dispatched)
        └── the concrete handler

Query handlers are registered as is (no unit of work).

Kind Types Validator
Commands CreateAgentCommand, CreateCrewCommand, CreateTaskCommand βœ… (CreateAgentCommandValidator, CreateCrewCommandValidator, CreateTaskCommandValidator)
AddMemoryCommand, CreateMemoryStoreCommand β€”
Queries GetAgentQuery, GetCrewQuery, GetTaskQuery, SearchMemoryQuery β€”

Callbacks and observability

Three observation surfaces exist, at different levels:

ICrewExecutionHook (Orkeon.Application.Crew) β€” the run-level hook every process strategy calls, on every exit (success, failure, cancellation): OnTaskStartedAsync, OnTaskCompletedAsync, OnCrewCompletedAsync, OnCrewFailedAsync, OnHumanInputAsync (default no-op), with task and crew snapshots (status, duration, tokens, cache split, skipped tasks). It is a single DI service; an exception it throws is logged and swallowed. Shipped implementations include AutoSummaryWriter (AUTO_SUMMARY.md), the orkeon run --events observer (see the run event bus), the orkeon-host progress hook, the MCP crew-tool progress hook and the forge's run observer. Every failed run reaches it once, OnCrewFailedAsync: the strategy reports a failure it saw, and the orchestrator reports one that came before any strategy ran β€” a memory that cannot work, a plan whose provider failed, a crew not found or refused by ValidateCanKickoff.

ICallbackHandler (Orkeon.Application.Callback) β€” task- and step-level notifications: OnTaskStartedAsync / OnTaskCompletedAsync around each agent execution (AgentExecutionService) β€” the completion's StepsExecuted is the number of turns the agent loop ran, each a model call with the tool calls it asked for, 0 when the task ended before its first β€”, and OnStepStartedAsync / OnStepCompletedAsync around each tool call of the agent loops β€” the chat-client, native and text loops alike (a streamed run goes through the same loops; there is no streaming loop of its own). A step's Action is tool:<name>; its completion carries the tool's raw result as Observation and Success = false when the tool failed, threw or was blocked by the guardian. CallbackOrchestrator (Orkeon.Application.Execution, the scoped ICallbackOrchestrator) fans each notification out to every ICallbackHandler registered in DI; a handler that throws is logged and skipped. The step notifications come from StepNotifyingToolInvocationPipeline, which wraps the tool-invocation point of the ExecutionOrchestrator (its Callbacks property, set by AddOrkeonApplication()). BaseCallbackHandler is the base to derive from; CompositeCallbackHandler fans out to several; LoggingCallbackHandler logs every notification but is not registered by default.

The streamed kickoff (ICrewOrchestrationService.KickoffStreamingAsync) β€” what one call observes, where the two surfaces above are registrations that serve every run of a container. It yields the run's events as they happen, in the vocabulary of the run event bus (RunEventKinds): each task's start and end (from the same dispatch point as the hook), each tool call (from the same pipeline as the step notifications), the model's text as it arrives (from the chat-client loop), then run.finished with the CrewOutput β€” after an error when the run failed. A crew run from inside a task β€” a tool that kicks another crew off β€” never writes into its caller's stream. See Getting started.


See also: ProcessTypes Β· Security Β· Back to index