Lux.Agent.Companies.SignalHandler behaviour (Lux v0.4.0)

View Source

Behaviour module that defines how company agents should handle different types of signals.

This module defines callbacks for:

  1. Task-related signals (assignments, updates, completion)
  2. Objective-related signals (evaluation, next steps)
  3. General signal handling

Summary

Callbacks

Called when an objective is completed. Should validate all steps are complete and prepare completion report.

Called for CEO agents to evaluate objective progress. Should assess current state and decide next actions.

Called for CEO agents to determine next step in objective. Should analyze dependencies and assign appropriate agent.

Called to update objective status. Should evaluate progress and update objective metadata.

Called when a task is assigned to the agent. Should evaluate the task and determine how to complete it.

Called when a task is completed. Should validate completion and prepare completion report.

Called when a task fails. Should prepare failure report with reason and any recovery steps.

Called to update task progress. Should evaluate current state and send progress update.

Callbacks

handle_objective_completion(signal, context)

(optional)
@callback handle_objective_completion(
  Lux.Schemas.Companies.ObjectiveSignal.signal(),
  context :: map()
) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called when an objective is completed. Should validate all steps are complete and prepare completion report.

handle_objective_evaluation(signal, context)

(optional)
@callback handle_objective_evaluation(
  Lux.Schemas.Companies.ObjectiveSignal.signal(),
  context :: map()
) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called for CEO agents to evaluate objective progress. Should assess current state and decide next actions.

handle_objective_next_step(signal, context)

(optional)
@callback handle_objective_next_step(
  Lux.Schemas.Companies.ObjectiveSignal.signal(),
  context :: map()
) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called for CEO agents to determine next step in objective. Should analyze dependencies and assign appropriate agent.

handle_objective_update(signal, context)

(optional)
@callback handle_objective_update(
  Lux.Schemas.Companies.ObjectiveSignal.signal(),
  context :: map()
) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called to update objective status. Should evaluate progress and update objective metadata.

handle_task_assignment(signal, context)

(optional)
@callback handle_task_assignment(
  Lux.Schemas.Companies.TaskSignal.signal(),
  context :: map()
) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called when a task is assigned to the agent. Should evaluate the task and determine how to complete it.

handle_task_completion(signal, context)

(optional)
@callback handle_task_completion(
  Lux.Schemas.Companies.TaskSignal.signal(),
  context :: map()
) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called when a task is completed. Should validate completion and prepare completion report.

handle_task_failure(signal, context)

(optional)
@callback handle_task_failure(Lux.Schemas.Companies.TaskSignal.signal(), context :: map()) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called when a task fails. Should prepare failure report with reason and any recovery steps.

handle_task_update(signal, context)

(optional)
@callback handle_task_update(Lux.Schemas.Companies.TaskSignal.signal(), context :: map()) ::
  {:ok, Lux.Signal.t()} | {:error, term()}

Called to update task progress. Should evaluate current state and send progress update.