Jason FAQ
(for version 1.3)

## Contents

- 1 General
  - 1.1 Why is the platform called "Jason"?
- 2 Internal Actions
  - 2.1 How to create a new internal actions?
- 3 Environment
  - 3.1 Is it possible to call an internal action from the environment?
  - 3.2 How to discover the name of the agents in the environment initialisation?
- 4 MAS Execution
  - 4.1 How to delay the MAS execution?
  - 4.2 Is it possible to add/remove an agent to/from a running MAS?
  - 4.3 How to log the execution?
  - 4.4 How to set the classpath for running a system?
  - 4.5 Which execution modes are available?
  - 4.6 How to run my application without JasonIDE
  - 4.7 How can I control agents' execution?
- 5 Jason Infrastructures
  - 5.1 What are infrastructures for?
  - 5.2 Which infrastructures are available?
  - 5.3 How to select an infrastructure?
  - 5.4 When should I use the SACI or JADE infrastructures?
  - 5.5 How to customise the JADE container?
  - 5.6 How to start a Jason agent with jade.Boot?
  - 5.7 Is it possible to use only the Jason BDI engine?
- 6 AgentSpeak Language
  - 6.1 What exactly are the cases where negative events of the forms "-!p" and "-?p" are generated?
  - 6.2 Does "+p" (or "-p") in a plan body cause two effects, i.e. updating the belief base and generating the events "+p" (or "-p")?
  - 6.3 Does "?p" in a plan body cause two effects, i.e. testing p from the belief base and generating the events "+?p"? Is "-?p" generated when a test goal "?p" fails? When does the test goal "?p" fail?
  - 6.4 It is claimed that open-world assumption is available. What does this mean? Do we have a three-valued logic?
  - 6.5 What's the difference between ! and !!?
  - 6.6 Why is Jason's plan failure mechanism different from other agent platforms?
  - 6.7 Which information is available to failure handling plans ?
- 7 Developing Jason
  - 7.1 How to build Jason from SourceForge SVN (subversion)?
  - 7.2 Do I have to use Jason with jEdit?
  - 7.3 How to create an Eclipse project for Jason?

# 1 General

## 1.1 Why is the platform called "Jason"?

Jason initially stood for `Java-based AgentSpeak interpreter used with SACI for multi-agent distribution over the net'. Since it not based only on SACI anymore (other infrastructures are available) and the acronyms was quite `forced', we decided the use Jason as a proper name for the interpreter.

The name is also somehow inspired by Jason in Greek mythology. Click here for an entry on "Jason" in the Perseus Encyclopaedia (Perseus is an excellent source of Classics, maintained by Tufts University).

# 2 Internal Actions

## 2.1 How to create a new internal actions?

The following steps will help you to define your internal action (IA). The steps 1-4,6 are automatically done by Jason IDE, see menu Plugin->Jason->New internal action".

1. In your MAS project directory, create a sub-directory called `myLib` (user's internal actions must be placed in a Java package, which provides a library of actions). In case this package directory is under your project directory, Jason automatically sets the classpath.

2. Copy an existing Jason internal action (`Jason/src/stdlib/concat.java`, for instance) to the `myLib` directory. This file will be used as a skeleton for your new IA.

3. Rename the file `myLib/concat.java` to `myLib/myIA.java`.

4. Edit this file and change the `package` name to `myLib`, and the class name to `myIA`.

   The code will likely look like

       package myLib;

       import jason.asSemantics.*;
       import jason.asSyntax.*;

       public class myIA extends DefaultInternalAction {
          public Object execute(TransitionSystem ts,
                                Unifier un,
                                Term[] args)
                        throws Exception {
             ....
          }
       }

5. Code the `execute` method in order to implement the internal action.

6. Compile the new class

       cd <your project directory>
       javac -classpath ...../Jason/lib/jason.jar:. myLib/myIA.java

7. Use the new IA in AgentSpeak sources, for example:

       +a(X) : true
          <- ... ;
             myLib.myIA(A,B);
             ... .

# 3 Environment

## 3.1 Is it possible to call an internal action from the environment?

Most of the internal actions (IAs) are developed from an agent perspective, since they are conceived to be called by agents. Thus the `execute` method needs an agent's `TransitionSystem` (TS) to be executed (e.g. `.my_name` only makes sense when called by an agent).

## 3.2 How to discover the name of the agents in the environment initialisation?

As the environment is created before the agents, the set of agents is empty when the environment is created and thus the method `getEnvironmentInfraTier().getRuntimeServices().getAgentsNames()` cannot be used. However, if the set of agents is defined only by the .mas2j project file (i.e., no agent is dynamically created), the name of the agents can be obtained from that file.

For instance, a project file called `ag-names.mas2j` can be passed as parameter to the environment as in the following example:

    MAS ag_names {
         environment: TestEnv("ag-names.mas2j")
         agents:   a #10;   b;
    }

The following code (in the environment initialisation) can then get all the names:

    public void init(String[] args) {
       // args[0] is the name of the project file
       try {
          // parse that file
          jason.mas2j.parser.mas2j parser =
              new jason.mas2j.parser.mas2j(new FileInputStream(args[0]));
          MAS2JProject project = parser.mas();

          List<String> names = new ArrayList<String>();
          // get the names from the project
          for (AgentParameters ap : project.getAgents()) {
             String agName = ap.name;
             for (int cAg = 0; cAg < ap.qty; cAg++) {
                String numberedAg = agName;
                if (ap.qty > 1) {
                   numberedAg += (cAg + 1);
                }
             names.add(numberedAg);
          }
       }
       logger.info("Agents' name: "+names);
       ...

# 4 MAS Execution

## 4.1 How to delay the MAS execution?

If you have an environment class, the easiest way is simply adding a thread `sleep' in the `executeAction` method. For example:

        ...
        public boolean executeAction(String agent, Term action) {
            ...
            try {
              Thread.sleep(500);
            } catch (Exception e) {}
            ...
        }

In case the agents do not act in the environment or there is no environment class, you should write a controller class (see [*]).

For instance, the controller class could be:

    package myPkg;
    import ...
    public class MyExecutionControl extends ExecutionControl {
        protected void allAgsFinished() {
            try {
              Thread.sleep(500);
            } catch (Exception e) {}
        }
    }

To use this controller, the project file must be

    MAS test {
        ...
        executionControl: myPkg.MyExecutionControl

        agents:  ...
    }

## 4.2 Is it possible to add/remove an agent to/from a running MAS?

The internal action `.create_agent` can be used to dynamically add a new agent into the running MAS. For example, when the plan:

    +a : true
       <- ... ;
          .create_agent(bob, "myAgent.asl");
          ... .

is executed, it will create a new agent called "bob" based on the AgentSpeak code available at file "myAgent.asl".

Analogously, the internal action `.kill_agent(<agent name>)` removes the agent identified by `<agent name>` from the current MAS. The `demos/create-agent` project that comes with the Jason distribution files has examples of using these features.

New agents can also be created in the user Java code, for example:

    public class myEnv extends Environment {
      ...
      public boolean executeAction(String ag, Term action) {
        ...
        getEnvironmentInfraTier().getRuntimeServices().
         .createAgent(
             "anotherAg",     // agent name
             "ag1.asl",       // AgentSpeak source
             null,            // default agent class
             null,            // default architecture class
             null,            // default belief base parameters
             null);           // default settings
      }
    }

The RuntimeServices interface, used in the code above, provides useful services transparently from the underlying infrastructure (Centralised, Saci, ...). The interface's methods include agent creation, agent killing, and halting the system (see the API documentation for more information).

Note that if you're using the SACI infrastructure, new agents (possibly not Jason agents, see [*]) can enter the MAS using SACI features for open MAS.

## 4.3 How to log the execution?

Jason uses the Java logging API to output messages into the console (the default console is called MASConsole). To change the log level or device, select the menu ``Plugins -> Jason -> Edit Log properties''. The default configuration file has comments that helps you customise your log. For instance, to output messages both into an XML file and in the console, you only need to set the log handler as in the following line:

    handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler

To get only console output (without the MASConsole GUI):

    handlers = java.util.logging.ConsoleHandler

## 4.4 How to set the classpath for running a system?

There are three ways to set the classpath of a project:

1. Create a lib directory in the project and include the jar files there. The ant script created by Jason to run the project (bin/build.xml) includes lib/*.jar in the classpath. This approach is used in examples/gold-miners.

2. In case you do not want to copy files into the project, the `classpath` entry in the .mas2j file can be used:

       MAS masid {
          agents: .......
          classpath: "../../jdom.jar";
                     "../../otherproject/classes";
                     "/apache/**/*.jar; // all jar files below /apache
       }

   Several items can be added as strings separated by ";". This approach is used in examples/sniffer.

3. If a more customised startup is required for your system, create a file named bin/c-build.xml with the template below:

       <project name ="mybuild" basedir="..">
           <import file="build.xml"/>

           <target name="user-init">
               <!-- add here all your custom initialisation -->
           </target>

           <target name="user-end">
               <!-- add here all your custom termination -->
           </target>

           <!-- you can also "override" other tasks from build.xml -->
       </project>

   If a c-build.xml file exists, it is used to run your application instead of build.xml that is automatically created by Jason.

## 4.5 Which execution modes are available?

Jason is distributed with three execution modes:

- Asynchronous: all agents run asynchronously. An agent goes to its next reasoning cycle as soon as it has finished its current cycle. This is the default execution mode.

- Synchronous: all agents perform one reasoning cycle at every "global execution step". When an agent finished its reasoning cycle, it informs the Jason controller and waits for a "carry on" signal. The Jason controller waits until all agents have finished their reasoning cycles and then sends the "carry on" signal to them.

  To use this execution mode, you have to set up a controller class in the .mas2j configuration, for example:

      MAS test {
          infrastructure: Centralised
          environment: testEnv

          executionControl: jason.control.ExecutionControl

          agents:  ...
      }

  The `jason.control.ExecutionControl` class implements exactly the "Jason controller" for the synchronous execution mode described above.

- Debug: this execution mode is similar to the synchronous mode, except that the Jason controller will also wait until the user clicks on a ``Step'' button before sending the ``carry on'' signal to the agents.

  To use this execution mode you can just press the ``debug'' button rather than the ``run'' button of the IDE, or you can set up a debug controller class in the .mas2j configuration, for example:

      MAS test {
          infrastructure: Centralised
          environment: testEnv

          executionControl: jason.control.ExecutionControlGUI

          agents:  ...
      }

  The `jason.control.ExecutionControlGUI` class implements the "Jason controller" with a GUI for debugging. This graphical tool is called "Jason's Mind Inspector", as it allows users to observe all changes in agents' mental attitudes after a (number of) reasoning cycle(s). This also applies to distributed agents (using SACI).

## 4.6 How to run my application without JasonIDE

The IDE (jEdit plugin) creates an Ant script (in the bin sub-directory of your application directory) and then simply runs this script to start your application. You can thus run it in a command prompt as follows:

       cd <the directory of you application>/bin
       ant

You can also run it as a normal Java application:

       cd <the directory of you application>
       export CLASSPATH=<your jars, jason.jar,...>
       java jason.infra.centralised.RunCentralisedMAS <yourproject.mas2j file>

You find more details about the environment (e.g. classpath) on the generated bin/build.xml file of your application.

A third way to run your application is to create a jar file for it. There is an option for that in the menu Plugins-Jason, or

       cd <the directory of you application>
       ant -f bin/build.xml jar
       java -jar <your application>.jar

##
4.7 How can I control agents' execution?

If you have other specific needs for controlling agents' execution, you have to implement an `ExecutionControl` sub-class and specify it in the .mas2j file.

You will most likely have to override the following methods:

    public void receiveFinishedCycle(String agName, boolean breakpoint) {
       super.receiveFinishedCycle(agName, breakpoint);
       ... your code ...
    }
    protected void allAgsFinished() {
       ... your code ...
    }

These methods are called by Jason when one agent has finished its reasoning cycle and when all agents have finished the current "global execution step".

To signal the agents to "carry on", your class can use the following code:

       fJasonControl.informAllAgsToPerformCycle();

You should have a look at the `ExecutionControlGUI` class for an example of how to do this, and the API documentation for further available methods inherited from `ExecutionControl`.

# 5 Jason Infrastructures

## 5.1 What are infrastructures for?

An infrastructure provides the following services for the MAS:

- communication (e.g., the SACI infrastructure implements communication based on KQML whilst JADE implements it using FIPA-ACL),
- control of the agent life cycle (creation, running, destruction).

## 5.2 Which infrastructures are available?

The current distribution of Jason has the following infrastructures:

Centralised:
  this infrastructure runs all agents in the same host. It provides fast startup and high performance for systems that can be executed in a single computer. It is also useful to test and develop (prototype) systems. Centralised is the default infrastructure.

Saci:
  provides distribution and communication based on KQML; click here for more details.

Jade:
  provides distribution and communication using Jade, which is based on FIPA-ACL. With this infrastructure, all tools available with JADE (e.g., Sniffer and Inspector) are also available to monitor and inspect Jason agents.

  Since Jason agents use KQML and JADE uses FIPA-ACL, we opted to translate the messages from KQML to FIPA-ACL and vice-versa to maintain the AgentSpeak programming the same for all infrastructures. The following table summarises the translation of the basic performatives:

  FIPA-ACL | KQML
  inform | tell
  query-ref | askOne
  request | achieve

  You can find more information about this infrastructure in the Jason-JADE mini-tutorial.

## 5.3 How to select an infrastructure?

In the `.mas2j` project file, use the `infrastructure' entry to select an infrastructure, for example to use Centralised:

    MAS auction {
        infrastructure: Centralised
        agents: ag1; ag2; ag3;
    }

to use Saci:

    MAS auction {
        infrastructure: Saci
        agents: ag1; ag2; ag3;
    }

and to use Jade:

    MAS auction {
        infrastructure: Jade
        agents: ag1; ag2; ag3;
    }

Note that the agents do not need to be changed for different infrastructures. The Jason Agent Architecture binds them to the available infrastructure.

##
5.4 When should I use the SACI or JADE infrastructures?

The centralised infrastructure does not support:

- execution of the agents at distributed hosts, and
- interoperability with non-Jason agents.

If you need any of these features, you should choose the SACI or JADE infrastructures (or implement/plug a new infrastructure for/into Jason yourself). The interoperability with non-Jason agents is achieved by SACI through KQML communication. An example of communication between Jason and SACI agents (implemented in Java) is available at Source Force.

## 5.5 How to customise the JADE container?

All parameters normally used to start a JADE container can be set in the menu Plugins -> Plugins Options -> Jason -> jade.Boot arguments. For instance, to start a non-main container when running the project, the following arguments can be used (supposing the main container is running at x.com):

    -gui -container -host x.com

## 5.6 How to start a Jason agent with `jade.Boot`?

The JADE agent wrapper should be used to start a Jason agent using `jade.Boot`, rather than doing it from the Jason IDE. For example, to start a Jason agent called `bob' based on the AgentSpeak source code in file `auctioneer.asl`, execute the following command in a shell:

    java jade.Boot "bob:jason.infra.jade.JadeAgArch(auctionner.asl)"

To start up also a simulated environment (implemented, for instance, in the `Env` class):

    java jade.Boot "\
     environment:jason.infra.jade.JadeEnvironment(Env) \
     bob:jason.infra.jade.JadeAgArch(auctionner.asl)"

The arguments for the environment have to follow the class name, for example:

    java jade.Boot "environment:jason.infra.jade.JadeEnvironment(Env arg1 arg2)"

In the case you need to start a more customised agent (architecture, belief base, ...), you can write (or reuse) a Jason project file with all the usual agent's parameters and then start the agent from this file. E.g.

    jade.Boot "bob:jason.infra.jade.JadeAgArch(j-project test.mas2j bob)"

The parameter `j-project` indicates that the following parameter (`test.mas2j` in the above example) is the Jason project. The third parameter is the name of the agent as defined in the .mas2j file.

The same approach can be used for the environment:

    jade.Boot "bob:jason.infra.jade.JadeAgArch(j-project test.mas2j)"

## 5.7 Is it possible to use only the Jason BDI engine?

If you want to use only the Jason interpreter for a variant of AgentSpeak, you can implement your own agent class where the Jason available infrastructures are not used. This class must function as an "overall agent architecture" for the AgentSpeak interpreter, i.e., it has to send percepts to the interpreter and get the agent actions (which result from the AgentSpeak "reasoning cycles").

Suppose you need a simple agent that interprets and reasons according to the following AgentSpeak source:

    +x(N) : N < 3  <- do(0).

    +x(N) : N >= 3 <- do(50).

The following class implements the required architecture (the complete code is available in the `demos' directory in the Jason distribution). This code simply adds `x(10)` into the agent's belief base through perception and get the output action, in this case `do(50)`.

    public class SimpleJasonAgent extends AgArch {
        public static void main(String[] a) {
           ...
           SimpleJasonAgent ag = new SimpleJasonAgent();
           ag.run();
        }

        public SimpleJasonAgent() {
             // set up the Jason agent and the
             // TransitionSystem (the BDI Engine where the AgentSpeak
             // Semantics is implemented)

             Agent ag = new Agent();
             new TransitionSystem(ag, new Circumstance(), new Settings(), this);
             ag.initAg("demo.asl"); // demo.asl is the file containing the code of the agent
        }

        public String getAgName() {
            return "bob";
        }

        public void run() {
            while (isRunning()) {
              // calls the Jason engine to perform one reasoning cycle
              getTS().reasoningCycle();
            }
        }

        // this method just add some perception for the agent
        public List<Literal> perceive() {
            List<Literal> l = new ArrayList<Literal>();
            l.add(Literal.parseLiteral("x(10)"));
            return l;
        }

        // this method gets the agent actions
        public void act(ActionExec action, List<ActionExec> feedback) {
            getTS().getLogger().info("Agent " + getAgName() +
                                 " is doing: " + action.getActionTerm());
            // return confirming the action execution was OK
            action.setResult(true);
            feedback.add(action);
        }

        public boolean canSleep() {
            return true;
        }

        public boolean isRunning() {
            return true;
        }

        public void sleep() {
        	try {   Thread.sleep(1000); } catch (InterruptedException e) {}
        }

        public void sendMsg(jason.asSemantics.Message m) throws Exception {
        }

        public void broadcast(jason.asSemantics.Message m) throws Exception {
        }

        public void checkMail() {
        }
    }

To run this agent:

    export CLASSPATH= ../../lib/jason.jar:.
    javac SimpleJasonAgent.java
    java  SimpleJasonAgent

The output will be

    [bob] Agent bob is doing: do(50)

Of course, the AgentSpeak code in this example cannot use communicative actions, since the specific architecture given above does not implement communication.

# 6 AgentSpeak Language

Thanks to Mehdi Dastani for these questions.

## 6.1 What exactly are the cases where negative events of the forms "-!p" and "-?p" are generated?

A test goal "?p" in the body of a plan first checks the belief base, and if it fails, it still tries to generate an internal event "+?p". This is because the test goal might have been meant to be a more sophisticated query for which the programmer created a whole plan with "+?p" as triggering event, then that plan could be executed to satisfy the test goal. Events "-!p" and "-?p" are only generated if an executing plan for "+!g" and "+?g" (respectively) fail. Here's what the manual says about this:

> Events for handling plan failure are already available in Jason, although they are not formalised in the semantics yet. If an action fails or there is no applicable plan for a subgoal in the plan being executed to handle an internal event with a goal addition "+!g", then the whole failed plan is removed from the top of the intention and an internal event for "-!g" associated with that same intention is generated. If the programmer provided a plan that has a triggering event matching "-!g" and is applicable, such plan will be pushed on top of the intention, so the programmer can specify in the body of such plan how that particular failure is to be handled. If no such plan is available, the whole intention is discarded and a warning is printed out to the console. Effectively, this provides a means for programmers to "clean up" after a failed plan and before "backtracking" (that is, to make up for actions that had already been executed but left things in an inappropriate state for next attempts to achieve the goal). For example, for an agent that persist on a goal "!g" for as long as there are applicable plans for "+!g", suffices it to include a plan "-g! : true <- true." in the plan library. Note that the body can be empty as a goal is only removed from the body of a plan when the intended means chosen for that goal finishes successfully. It is also simple to specify a plan which, under specific condition, chooses to drop the intention altogether (by means of a standard internal action mentioned below).

## 6.2 Does "+p" (or "-p") in a plan body cause two effects, i.e. updating the belief base and generating the events "+p" (or "-p")?

Yes, it causes both effects. Note, importantly, that one of the interpreter configuration options allow the user to choose whether the event (if it is by chance relevant to any plans the agent has) will be treated as internal (pushed on top of that same intention) or external (a new intention - i.e., a new "focus of attention" - is created).

## 6.3 Does "?p" in a plan body cause two effects, i.e. testing p from the belief base and generating the events "+?p"? Is "-?p" generated when a test goal "?p" fails? When does the test goal "?p" fail?

When "?p" is executed, first the interpreter tries a simple query to the belief base. If that doesn't succeed, before failing the intention, first an internal event for "+?g" is generated, if there are no applicable plans for such event, then the plan fails (fails "normally", i.e., for the "no applicable plans" reason) -- there could be still a "-?g" plan to be tried; if there's none, the intention is discarded and a message printed to the console to let the user know.

## 6.4 It is claimed that open-world assumption is available. What does this mean? Do we have a three-valued logic?

No, we don't use three-valued logic, strictly speaking. There is a "strong negation" operator "`~`". When assuming open world, the user models the environment with a set of propositions known to be explicitly true and a set of propositions known to be explicitly false of the environment at a certain moment in time (the latter are literals preceeded by the `~` operator). Of course, there is still default negation (as usual in logic programming languages), so you can say, in the context of a plan, "not p(t) & not `~`p(t)" to check if the agent is uncertain about "p(t)". Note that it's completely up to the user to prevent paraconsistency (or to use it, if they so wish). You could add internal beliefs (or have beliefs from perception of the environment) that p(t) is true and that p(t) is also true: Jason won't do consistency checks for you! But you can easily implement such consistency check, or indeed have more elaborate belief revisions algorithms by overriding the belief update and belief revision methods in Jason (the belief revision method by default does nothing). Finally, note that strong negation can also appear in the triggering events, plan body, and anywhere a literal can appear.

## 6.5 What's the difference between ! and !!?

The difference between ! and !! is that the latter causes the goal to be pursued as a separate intention. Within the body of a plan in one intention, if you have "!g1; !g2" the agent will attempt to achieve g2 only after achieving (or finishing executing a plan for) g1. If you say "!!g1; !g2" the agent will then have another separate intention to achieve g1 and can immediately start attempting to achieve g2. What will be done first (executing a bit of the intention with g1 or the old intention with g2) will depend on the choices that the intention selection function makes.

You may have noticed !! is often used at the end of recursive plans (when the recursive call does not have free variables to be instantiated) as in the following code:

    +!g : end_recursion_context.
    +!g : true <- action1; !!g.

In this case, the !! is used to avoid Jason creating long stacks of (empty) plans, so the operator just allows Jason to process the recursion more efficiently.

## 6.6 Why is Jason's plan failure mechanism different from other agent platforms?

Some other platforms handle plan failure in the following way. When a plan is selected as an intended means to achieve a goal (more generally, to handle an event), other applicable plans might be available or indeed other instantiations of the plan's variables (to make the context a logical consequence of the belief base) might be possible. Those platforms then make a "note" of all those plans and plan instantiations. If the plan currently being executed fails, another plan is chosen from that set of plans initially recorded as alternative plans for handling that event. This has the great advantage that the platform does not have to check for applicable plans again, and has as disadvantage the fact that possibly the agent's beliefs have changed and so plans considered applicable at the time the first plan was selected, are actually no longer applicable (yet they will be attempted, which increases the chances of the chosen alternative plan failing as well).

In Jason, we opted for a different approach. When a plan with a triggering event "`+!g`" fails, we generate an event "`-!g`" and if the programmer provided a plan for that event, and that plan is currently applicable, that plan is pushed on top of the intention where the failed plan is. In the general case, the programmer will have included in that "`-!g`" plan another attempt to achieve "`g`". When this happens, all relevant plans will be checked again to find the set of currently applicable plans. Under the assumption that the contexts have been well defined by the programmer, only plans that now stand a chance of succeeding will be applicable. Differently from the above mechanism, here we have the advantage of being better updated on the set of actually applicable plans, but might be less efficient in that more checks need to be done.

Another disadvantage of this approach is that to make sure a plan will only be tried once (if in a particular application this is important, although this is not always the case, surely), as it happens in other platforms, the user will have to use, e.g., the belief base to keep track of the previously attempted plans, or else to have the applicable plan selection function checking the failed plans in the stack of plans forming that intention (note that the failed plans are still there and will only be removed, without executing further, when the respective plan for "`-!g`" finishes) to decide which ones not to use anymore. Off course the latter requires considerable Java programming). For the first alternative, there is work on ``plan patterns'' and pre-processing directives which take care of automating this for the programmer.

On the other hand, there is an extra advantage of the use of the Jason plan failure handling mechanism. Pure "backtracking" as used in logic programming might not always make sense in an agent program. Recall that besides "sub-goals", plan bodies have actions. These actions, by definition, change something that is outside the agent itself (i.e., the environment), so they cannot automatically be "undone" by the interpreter in the process of backtracking. It is therefore possible that none of the plans originally written (with a particular set of initial situations in mind) to achieve the goal will be applicable anymore. At least in some cases, it might be sensible to let the "`-!g`" plan perform the necessary actions to bring the environment back to a "reasonable" state in which the original plans to achieve the goal can then be used again, rather than writing more alternative plans for the original goal considering all possible situations in which the agent can find itself when attempting to achieve the goal.

## 6.7 Which information is available to failure handling plans ?

When a plan fails, the plan that handles the corresponding event (that has the form of `-!g`) may use failure information to provide a suitable solution. This information is provided by two means:

Internal actions:
  the internal action `.current_intention(I)` unifies `I` with a representation of the stack of the current intention. By inspecting this stack, the context of the failure can be discovered.

  It follows an example of `I` (provided by the execution of the example available in `demos/failure`):

      intention(1,
        [
         im(l__6[source(self)], { .current_intention(I); ... },  [map(I,...),...]),
         im(l__5[source(self)], { .fail },                       []),
         im(l__4[source(self)], { !g5(X); .print(endg4) },       [map(X,failure)]),
         im(l__3[source(self)], { !g4(X); .print(endg3) },       [map(X,failure)]),
         im(l__2[source(self)], { !g3(X); .print(endg2) },       [map(X,failure)]),
         im(l__1[source(self)], { !g2(X); .print(endg1) },       [map(X,failure)]),
         im(l__0[source(self)], { !g1(X); .print("End, X=",X) }, [map(X,failure)])
        ]
      )

  You can find more information in the documentation of the current_intention pre-defined internal action.

Annotations:
  every failure event is annotated with at least the following information:
  - `error(<atom: error id>)`: the identification of the type of failure; values used by are:
    - `no_applicable`: failure caused by no applicable plan;
    - `no_relevant`: failure caused by no relevant plan;
    - `no_option`: failure caused by no option being selected by the selectOption function;
    - `constraint_failed`: failure caused by a constraint in the plan that was not satisfied;
    - `ia_failed`: failure caused by an error in an internal action (it throws an exception or returned false);
    - `action_failed`: the failure was caused by a failure in the execution of an action in the environment (i.e., the action execution returned "false");
    - `ask_failed`: the failure is caused by the lack of response to an ask message (with deadline);
    - `wrong_arguments`: failure caused by wrong number or type of arguments given to an internal action;
    - `unknown`: other causes;

  - `error_msg(<string>)`: the human readable message of the error
  - `code(<literal>)`: the plan body literal that failed;
  - `code_src(<string>)`: the file name with the source code where the plan that failed is defined;
  - `code_line(<int>)`: the line number within that file.

  An example of failure event and its annotations:

      -!g[error(ia_failed),
          error_msg("internal action .my_name failed"),
          code(".my_name(bob)"),
          code_src("/tmp/x.asl"),
          code_line(18)]

  Note that the plan that handles this event is not obliged to use any these annotations, or it could make use of a subset of them, for example:

      -!g[error(ia_failed)]       <- ... plan to handle error of type \ia_failed' ....
      -!g[error(no_applicable)]   <- ... plan to handle error of type 'no_applicable'
      -!g[code_src("/tmp/x.asl")] <- ... plan to handle error in plans of file x.asl

  The internal actions defined by the user can add new annotations to indicate particular types of errors (see the API documentation of JasonException for more information about that).

# 7 Developing Jason

## 7.1 How to build Jason from SourceForge SVN (subversion)?

The SVN repository maintains the latest version of the Jason's sources, so you will eventually need to build Jason from the SVN. To do this the following software is required:

- an SVN client program and
- Ant version >= 1.6.2.

The steps to build Jason are:

1. download the sources from SVN:

       mkdir Jason-svn
       cd Jason-svn
       svn co https://jason.svn.sourceforge.net/svnroot/jason/trunk .

2. create the `jason.jar` file and the jEdit plugin:

       ant clean
       ant jar
       ant plugin

3. create the API documentation:

       ant apidoc

   More information is available at SourceForge page.

## 7.2 Do I have to use Jason with jEdit?

No, Jason is also available as a plugin to Eclipse, developed mostly by Germano Fronze; click here for more information, including installation instructions.

A command line option is also available. To compile a project:

    <jason installation path>/bin/mas2j.sh <your project.mas2j>

an Ant script is created in the `bin` directory. To run:

    ant -f bin/build.xml

## 7.3 How to create an Eclipse project for Jason?

This might be useful if you are planning to contribute code for Jason itself.

1. Select new Java Project wizard in Eclipse.
2. In "create project from existing source" select the directory where is installed. [Next]
3. Set `"src"` directory for the sources.
4. Set `"bin/classes"` for "Default output folder".
5. Add all jars in `"lib"` as "Libraries". [Finish]