Provides a type-safe way to modify agent state through discrete, validated directives.

## Overview

Directives are immutable instructions that can be applied to an agent to modify its state in predefined ways. Each directive type is implemented as a separate struct with its own validation rules, helping ensure type safety and consistent state transitions.

## Available Directives

• Enqueue - Adds a new instruction to the agent's pending queue

  • Requires an action atom
  • Supports optional params and context maps
  • Supports optional opts keyword list
  • Example: %Enqueue{action: :move, params: %{location: :kitchen}}

• RegisterAction - Registers a new action module with the agent

  • Requires a valid module atom
  • Example: %RegisterAction{action_module: MyApp.Actions.Move}

• DeregisterAction - Removes an action module from the agent

  • Requires a valid module atom
  • Example: %DeregisterAction{action_module: MyApp.Actions.Move}

• Spawn - Spawns a child process under the agent's supervisor

  • Requires a module atom and arguments
  • Example: %Spawn{module: MyWorker, args: [id: 1]}

• Kill - Terminates a child process

  • Requires a valid PID
  • Example: %Kill{pid: #PID<0.123.0>}

• StateModification - Modifies agent state at a given path

  • Requires an operation and path
  • Supports optional value
  • Example: %StateModification{op: :set, path: [:config, :mode], value: :active}

## Usage

Directives can be applied to either an Agent or ServerState struct:

  # Apply to Agent - returns updated agent
  {:ok, updated_agent} = Directive.apply_directives(agent, directives)

  # Apply to ServerState - returns updated state
  {:ok, updated_state} = Directive.apply_directives(server_state, directives)

Each function validates directives before applying them and returns either:

• {:ok, updated_state} - Directives were successfully applied
• {:error, reason} - Failed to apply directives

## Validation

Each directive type has its own validation rules:

• Enqueue requires a non-nil atom for the action
• RegisterAction requires a valid module atom
• DeregisterAction requires a valid module atom
• Spawn requires a valid module atom and arguments
• Kill requires a valid PID

Failed validation results in an error tuple being returned and processing being halted.

## Error Handling

The module uses tagged tuples for error handling:

• {:ok, updated_state} - Successful application of directives
• {:error, reason} - Failed validation or application

Common error reasons include:

• :invalid_action - The action specified in an Enqueue is invalid
• :invalid_action_module - The module specified in a Register/DeregisterAction is invalid
• :invalid_module - The module specified in a Spawn is invalid
• :invalid_pid - The PID specified in a Kill is invalid
• :invalid_topic - The topic specified in a broadcast/subscribe/unsubscribe directive is invalid

## Ideas Change Mode Change Verbosity Manage Router (add/remove/etc) Manage Skills (add/remove/etc) Manage Dispatchers (add/remove/etc)