LightSOPLang Overview

Why LightSOPLang Exists

The Achilles Agents Library treats LightSOPLang as the glue that links high level plans with concrete skill or tool executions. Orchestration skills embed scripts to coordinate multiple downstream skills without relying on ad-hoc imperative code. MCP skills use the same notation to describe deterministic tool sequences. The language is intentionally compact so that planners can emit or edit scripts in a predictable way while leaving room for automatic regeneration when an English description is provided.

Interpreter Responsibilities

The interpreter defined in lightSOPLang/interpreter.mjs loads scripts, resolves dependencies between declarations, and executes commands through a registry supplied by the hosting skill family. It tracks variable states, propagates failures, and handles cancellation. When a script begins with #!english the interpreter delegates to the configured LLMAgent, asking it to generate executable LightSOPLang. The generated code is validated, executed, and, if necessary, regenerated when a command fails.

Using LightSOPLang in Sessions

In addition to one-off plan generation, Achilles exposes a session-based API for working with LightSOPLang plans incrementally. LLMAgent.startSOPLangAgentSession(skillsDescription, initialPrompt, options) constructs a SOPAgenticSession that owns an evolving LightSOPLang script.

Each call to session.newPrompt(prompt) feeds a new natural language requirement together with the current script back to the LLM. The LLM is instructed to extend or adjust the existing declarations so that the combined script satisfies both old and new requirements. Existing variables are generally kept stable; new behaviour is expressed with new variables, and only when the requirement truly changes a step will the corresponding declaration be updated. When declarations change, the interpreter’s dependency tracking automatically recalculates affected variables.

This pattern lets you treat LightSOPLang as a live, revisable plan: the LLM edits the DSL while the interpreter guarantees consistent execution and propagation of changes.

Registries and Skill Families

Each skill family provides a command registry that the interpreter uses to execute statements. Orchestration skills map command names to other skills and record plan entries. MCP skills map command names to allowed tools and capture tool usage. Registries expose two methods: executeCommand(payload, responder) runs the requested action, while listCommands() returns documentation that the interpreter supplies to the LLM regeneration prompt. This separation allows LightSOPLang scripts to remain agnostic of the concrete execution environment.

Relationship with Tutorials

The interactive tutorial does not execute LightSOPLang because conversational flows are driven by the executor. The orchestration and MCP tutorials both reference scripts drawn from tests/recursiveAgent/recursiveAgentFixtures/.AchillesSkills. Those scripts form part of the regression suite and demonstrate how LightSOPLang encapsulates business logic in Markdown descriptors rather than ad-hoc JavaScript.