Terminology Wiki
This page is the canonical source for project-specific terms used by the HTML documentation and design specifications.
MainAgent
MainAgent is the top-level class through which an application integrates AchillesAgentLib. It discovers workspace skill descriptors below startDir, registers them with specialized subsystems, exposes direct skill execution, and owns one reusable LoopAgentSession for general executePrompt() calls. It creates a default SecuritySupervisor or accepts one from the application and passes that supervisor into the agentic session. It does not make provider calls itself; its llmAgent performs those calls, and each subsystem owns the execution rules for its skill family. Package-internal skills are excluded by default unless the application explicitly enables them.
LLMAgent
LLMAgent is the required class for all model interactions in AchillesAgentLib. It accepts concrete model names, semantic tags, reasoning effort, and caller-provided model mappings, then delegates the resolved request to the provider invoker. It also supplies intent and confirmation helpers, response coercion, traffic counters, cancellation, and factories for Loop and SOP sessions. It does not own workspace discovery or persistent project memory.
Agentic session
An agentic session is a stateful runtime object that accepts prompts across turns, asks LLMAgent for decisions or plans, invokes an approved tool surface, and retains the information required for continuation. AchillesAgentLib provides adaptive Loop sessions and plan-first SOP sessions. Sessions are in-memory objects; persistent memory requires a separate caller-owned store such as AKU or MarkdownDataStore.
LoopAgentSession
LoopAgentSession is the adaptive session used by MainAgent.executePrompt(). For each turn, it repeatedly requests a structured next-tool decision, applies supervisor approval, executes the tool, and records the result until it emits a final answer, needs input, is interrupted, or reaches a configured limit. It stores conversation history, turn records, tool calls, intermediate tool variables, failures, model options, and the latest answer. History compression may summarize older entries while retaining a configured recent window.
SOPAgenticSession
SOPAgenticSession is the plan-first session used by orchestration flows. It asks LLMAgent to produce LightSOPLang, validates the command surface and dependency topology, executes ready commands, and performs bounded replanning when failures require correction. It retains the current plan, execution variables, last answer, failures, pending user-input command, preparation context, and history. The supplied command registry remains its execution boundary.
Skill
A skill is a portable folder whose descriptor states its interface and whose local files implement or specify one reusable operation. MainAgent recognizes cskill.md, dcgskill.md, oskill.md, and tskill.md families and delegates each family to a specialized subsystem. A skill may be enabled or disabled in the MainAgent catalog; disabled records remain discoverable but cannot be built, exposed as session tools, or executed directly.
Code skill
A code skill uses cskill.md and executable ESM under its own src/ folder. CodeSkillsSubsystem parses its descriptor, prepares its record, optionally builds missing source from a local specs/ tree, imports the entry module, and calls the exported action. The portable implementation remains inside the skill folder and generated source must be regenerated from its specification rather than edited directly.
Skill subsystem
A skill subsystem is the execution component assigned to one descriptor family by SubsystemFactory. Subsystems parse descriptors, perform fast registration-time preparation, optionally run explicit asynchronous builds, and execute prompts. MainAgent owns the catalog and delegates these family-specific operations; no subsystem is a second top-level agent.
LightSOPLang
LightSOPLang is the repository's compact plan language for named commands, variables, dependencies, parallel readiness, and failure behavior. SOPAgenticSession generates and validates a LightSOPLang plan before handing it to the execution runtime. Only commands from the session registry may execute, and cancellation or code-update rules can invalidate a running plan.
Agentic Knowledge Units
Agentic Knowledge Units, abbreviated AKU, are the deterministic local-memory API exported by AchillesAgentLib. A caller configures a project root for file and folder registration and may independently configure a persistence root containing Knowledge Units and indexed records for documents, files, folder scopes, links, events, runs, results, validations, and ingested sessions. Callers control what to store and validate; AKU provides schemas, locked atomic persistence, repair, lexical search, graph scoping, and character-budgeted ContextPack construction. It is not a vector database and does not invoke an LLM.
ContextPack
A ContextPack is an ordered, character-budgeted retrieval result built from AKU records. The builder selects lexically relevant and optionally scoped candidates, applies per-KU diversity and quotas, and can include state or history when requested. The pack is data for a caller to inject into later work; AKU does not send it to a model automatically.
BacklogManager
BacklogManager is a public utility that stores active tasks and completed history in paired JSON files identified by one base path. It supports task creation, alternatives, approval, updates, and moving resolved tasks to history. It does not schedule or execute tasks, and its public task identifiers are one-based.
MarkdownDataStore
MarkdownDataStore is a public filesystem utility that maps a validated type and file name to a Markdown record below a configured data directory. Each record contains numbered level-three sections that can be selected, appended, replaced, updated, or deleted. It also parses and renders list, dialogue, and key-value conventions. It protects its root boundary but does not provide database transactions across several files.
Model tag
A model tag is a semantic routing label supplied to LLMAgent, such as an application-defined tag for documentation, testing, or orchestration. An application-supplied modelConfig can map a tag directly to a model; otherwise the provider catalog may select a matching model. An explicit concrete model has higher priority than tag-based selection, and unconfigured tags do not guarantee a particular provider or tier.
SecuritySupervisor
SecuritySupervisor is the MainAgent collaborator that decides whether a session tool call may proceed, must be denied, or may be remembered as always approved. Sessions consult it before executing controlled tools. It governs approval decisions but does not discover tools or call the LLM provider.