### Install and Setup planutils

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

These commands install the planutils Python package, set up its environment, and activate it for use. It's a prerequisite for accessing multiple PDDL planners.

```bash
pip install planutils
planutils setup
planutils activate
```

--------------------------------

### Start planutils Server

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

Installs the Flask web framework and starts the planutils server on port 5555. This server provides a remote interface for PDDL planning capabilities.

```bash
pip install flask
planutils server --port 5555
```

--------------------------------

### Install a Specific Planner with planutils

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

Demonstrates how to install a specific PDDL planner, 'lama', using the planutils command-line tool. This allows users to easily add new planners to their environment.

```bash
planutils install lama
```

--------------------------------

### PDDL Plan Happenings Syntax Example

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

Demonstrates the syntax for PDDL plan happenings, including timed initial fluents, timed initial literals, action start/end times, and re-occurring actions. This format is used for detailed temporal plan analysis.

```PDDL Plan Happenings
;;!domain: airport-ground-operations
;;!problem: _1plane

; timed initial fluent
1.000: (= (available_fuel-truck truck1) 1000)
; timed initial literal
5.000: set (final-approach p1)
5.001: start (land p1 rw1)
5.100: unset (final-approach p1)
7.001: end (land p1 rw1)

; re-occurring actions
10.001: start (land p1 rw1) #2
12.001: end (land p1 rw1) #2

```

--------------------------------

### Control Search Debugger via VSCode Commands

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet shows how to start and stop the search debugger using VSCode commands. It also includes configuration examples for the search debugger and a debuggable planner. The debugger aids in analyzing planning search processes.

```typescript
import { SearchDebugger } from './searchDebugger/SearchDebugger';

// Start search debugger
await vscode.commands.executeCommand('pddl.searchDebugger.start');

// Stop search debugger
await vscode.commands.executeCommand('pddl.searchDebugger.stop');

// Configure search debugger
const searchDebuggerConfig = {
    "pddlSearchDebugger.defaultPort": 0,
    "pddlSearchDebugger.stateIdPattern": "^(\\d+)$",
    "pddlSearchDebugger.stateLogPattern": "^\\s*State ID:\\s*(.*)\\s*$"
};

// Configure planner for search debugging
const plannerWithDebug = {
    "kind": "EXECUTABLE",
    "path": "/path/to/planner",
    "title": "Debuggable Planner",
    "searchDebuggerSupport": "HttpCallback",
    "searchDebuggerCommandLineSyntax": "--search-tree-dump=http://localhost:$(port)"
};

// Example: Start search debugger and run planner
async function debugPlanningSearch(domainUri: vscode.Uri, problemUri: vscode.Uri) {
    // Start search debugger
    await vscode.commands.executeCommand('pddl.searchDebugger.start');

    // Configure planner execution target to search debugger
    const config = workspace.getConfiguration('pddlPlanner');
    await config.update('executionTarget', 'Search debugger', ConfigurationTarget.Global);

    // Run planner - output will go to search debugger
    await vscode.commands.executeCommand('pddl.planAndDisplayResult', domainUri, problemUri);
}
```

--------------------------------

### Mock Search Debugger Implementation in TypeScript

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

Provides an example implementation of the HTTP client required for the planning engine to participate in visual search debugging. This code defines the expected data format for search progress information.

```typescript
import * as express from 'express';
import * as cors from 'cors';

const app = express();
const port = 3000;

app.use(cors());
app.use(express.json());

app.post('/search-progress', (req, res) => {
    const searchData = req.body;
    console.log('Received search progress data:', JSON.stringify(searchData, null, 2));
    // In a real implementation, this data would be processed and visualized
    res.sendStatus(200);
});

app.listen(port, () => {
    console.log(`Mock Search Debugger listening at http://localhost:${port}`);
});

```

--------------------------------

### PDDL Planner Configuration (TypeScript)

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

Details how to configure various PDDL planners, including executables and online services, through VS Code settings. It shows how to define multiple planners and select a preferred one, with an example of adding a custom planner configuration programmatically.

```typescript
import { PlannersConfiguration } from './configuration/PlannersConfiguration';

// Configure multiple planners in settings.json
const plannerConfig = {
    "pddl.planners": [
        {
            "kind": "EXECUTABLE",
            "path": "/path/to/planner",
            "title": "Fast Downward",
            "canConfigure": true,
            "syntax": "$(planner) $(options) $(domain) $(problem)"
        },
        {
            "kind": "SERVICE_SYNC",
            "url": "http://localhost:5555/solve",
            "title": "Local Planner Service",
            "canConfigure": true
        },
        {
            "kind": "PLANNING_AS_A_SERVICE",
            "url": "https://solver.planning.domains:5001/package",
            "title": "Planning.domains solver",
            "canConfigure": false
        }
    ],
    "pddl.selectedPlanner": "Fast Downward"
};

// Select planner programmatically
await vscode.commands.executeCommand('pddl.selectPlanner');

// Example: Add a custom planner configuration
async function addCustomPlanner() {
    const config = workspace.getConfiguration('pddl');
    const planners = config.get<any[]>('planners', []);

    planners.push({
        kind: "EXECUTABLE",
        path: "/opt/planners/lama/fast-downward.py",
        title: "LAMA First",
        canConfigure: true,
        syntax: "$(planner) --alias lama-first $(domain) $(problem)"
    });

    await config.update('planners', planners, ConfigurationTarget.Global);
    await config.update('selectedPlanner', 'LAMA First', ConfigurationTarget.Global);
}
```

--------------------------------

### JavaScript Function for Plan Visualization

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This JavaScript code defines a function `visualizePlanHtml` intended for generating HTML-based plan visualizations. It takes the plan data and desired width as input and should contain the logic for rendering the plan. The example provides a placeholder for the visualization logic.

```javascript
function visualizePlanHtml(plan, width) {
   const height = 250;
   return `...`; // your plan visualization logic goes here
}
module.exports = {
   visualizePlanHtml: visualizePlanHtml 
};
```

--------------------------------

### Generate Problem Template using Nunjucks in VSCode

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet demonstrates generating a problem template using Nunjucks. It shows a template string along with example data.  The configuration showcases preprocessing the problem definition.

```typescript
// Problem template with Nunjucks
const problemTemplate = `
(define (problem generated-problem) (:domain {{ domain_name }})

(:objects
    {% for obj in objects %}
    {{ obj.name }} - {{ obj.type }}
    {% endfor %}
)

(:init
    {% for fact in initial_facts %}
    ({{ fact }})
    {% endfor %}
)

(:goal (and
    {% for goal in goals %}
    ({{ goal }})
    {% endfor %}
))
)
`;

// Data file (data.json)
const templateData = {
    "domain_name": "logistics",
    "objects": [
        { "name": "truck1", "type": "truck" },
        { "name": "location1", "type": "location" },
        { "name": "package1", "type": "package" }
    ],
    "initial_facts": [
        "at truck1 location1",
        "at package1 location1"
    ],
    "goals": [
        "at package1 location2"
    ]
};

// Test configuration with preprocessing
const testWithTemplate = {
    "defaultDomain": "domain.pddl",
    "cases": [
        {
            "label": "Small instance",
            "problem": "problem_template.pddl",
            "preProcess": {
                "kind": "nunjucks",
                "data": "small_data.json"
            }
        },
        {
            "label": "Python preprocessor",
            "problem": "problem_template.pddl",
            "preProcess": {
                "kind": "python",
                "script": "../scripts/generate_problem.py",
                "args": ["large_instance.json"]
            }
        }
    ]
};
```

--------------------------------

### PDDL Parser Configuration (TypeScript)

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

Explains how to configure the PDDL parser settings within the VS Code extension, including specifying the executable path or service, setting command-line options, and adjusting the delay before parsing. It provides an example for configuring the VAL parser.

```typescript
import { PddlConfiguration } from './configuration/configuration';

// Configure PDDL parser executable or service
const configuration = workspace.getConfiguration('pddlParser');
await configuration.update('executableOrService', '/path/to/parser.exe', ConfigurationTarget.Global);

// Set parser command-line options
await configuration.update('executableOptions', '$(domain) $(problem)', ConfigurationTarget.Global);

// Configure parsing delay (in seconds)
await configuration.update('delayInSecondsBeforeParsing', 3, ConfigurationTarget.Global);

// Example: Configure VAL parser
async function configureValParser() {
    const config = workspace.getConfiguration('pddlParser');
    await config.update('executableOrService', '/usr/local/bin/validate', ConfigurationTarget.Global);
    await config.update('executableOptions', '$(domain) $(problem)', ConfigurationTarget.Global);

    vscode.window.showInformationMessage('VAL parser configured successfully');
}
```

--------------------------------

### Debug PDDL Plan Happenings

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet focuses on debugging PDDL plan happenings using VSCode commands. It includes executing happenings, showing effects, generating plan-resume test cases, and an example of creating and executing a happenings file. Dependencies include the VSCode API and filesystem operations.

```typescript
// Execute happenings and show effects
await vscode.commands.executeCommand('pddl.happenings.execute');

// Generate plan-resume test cases
await vscode.commands.executeCommand('pddl.happenings.generatePlanResumeCases');

// Example happenings file format
const happeningsContent = "\n;;!domain: airport-ground-operations\n;;!problem: simple-problem\n\n; timed initial fluent\n1.000: (= (fuel-available truck1) 1000)\n; timed initial literal\n5.000: set (final-approach plane1)\n5.001: start (land plane1 runway1)\n7.001: end (land plane1 runway1)\n\n; recurring actions\n10.001: start (taxi plane1 runway1 gate1) #2\n12.001: end (taxi plane1 runway1 gate1) #2\n";

// Example: Create and execute happenings
async function createAndExecuteHappenings(domainPath: string, problemPath: string) {
    const happeningsPath = problemPath.replace('.pddl', '.happenings');

    await workspace.fs.writeFile(
        Uri.file(happeningsPath),
        Buffer.from(happeningsContent)
    );

    const doc = await workspace.openTextDocument(happeningsPath);
    await vscode.window.showTextDocument(doc);

    // Execute happenings and show effects
    await vscode.commands.executeCommand('pddl.happenings.execute');
}
```

--------------------------------

### PDDL Search Debugger: Add Initial State Payload

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Search-tree-debugger-API

Defines the JSON payload structure for adding the initial state to the search tree. It includes state identifiers, cost, and time information. This is the starting point for visualizing the planning search.

```json
{
    "id": "0",
    "parentId": null,
    "g": 0,
    "earliestTime": 0.001000
}
```

--------------------------------

### Visualize State in Div (JavaScript)

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/How-to-implement-custom-plan-state-visualization

An example JavaScript function that populates a given HTML div element with a visualization of the final state of a PDDL plan. It iterates through the final state and logs variable values.

```javascript
/**
 * Populates the `planVizDiv` element with the plan visualization of the `finalState`.
 * @param {HTMLDivElement} planVizDiv host element on the page
 * @param {Plan} plan plan to be visualized
 * @param {{variableValue: string, value: number | boolean}[]} finalState final state of the `plan`
 * @param {number} displayWidth desired width in pixels
 */
function visualizeStateInDiv(planVizDiv, plan, finalState, displayWidth) {
   for (const v of finalState) {
      console.log(`${v.variableName}: ${v.value}`);
   }

    //...
}
```

--------------------------------

### VS Code PDDL: Configure State ID Pattern Setting

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Search-tree-debugger-API

Shows an example of configuring a regular expression pattern for interpreting state IDs. This is useful when state IDs are not simple numbers and require custom parsing for log file correlation.

```json
{
    "pddlSearchDebugger.stateIdPattern": "State \\"(\\d+)\\\""
}
```

--------------------------------

### PDDL Plan File Header for Preview

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This PDDL snippet shows the required header format for a `.plan` file to enable the 'PDDL: Preview plan' command in VS Code. The `;;!domain` and `;;!problem` lines link the plan to its corresponding domain and problem definitions, which is necessary for visualization.

```pddl
;;!domain: domain-name
;;!problem: problem-name
```

--------------------------------

### GET /about

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Search-tree-debugger-API

Performs a health check to verify if the search debugger service is running.

```APIDOC
## GET /about

### Description
This endpoint may be used for a health check to see if the service is listening.

### Method
GET

### Endpoint
/about

### Response
#### Success Response (200)
- **status** (string) - Indicates the service status (e.g., "OK").
- **version** (string) - The version of the search debugger service.

#### Response Example
```json
{
  "status": "OK",
  "version": "1.0.0"
}
```
```

--------------------------------

### Manage Planning.Domains Sessions with VSCode Commands

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet demonstrates how to interact with Planning.Domains sessions using VSCode commands. It covers loading, refreshing, committing, discarding, duplicating, sharing, and generating classroom sessions.  It facilitates collaborative planning and problem-solving.

```typescript
// Download Planning.Domains session
await vscode.commands.executeCommand('pddl.planning.domains.session.load');

// Refresh session from server
await vscode.commands.executeCommand('pddl.planning.domains.session.refresh');

// Commit local changes
await vscode.commands.executeCommand('pddl.planning.domains.session.commit');

// Discard local changes
await vscode.commands.executeCommand('pddl.planning.domains.session.discard');

// Duplicate session as writable
await vscode.commands.executeCommand('pddl.planning.domains.session.duplicate');

// Share session via email
await vscode.commands.executeCommand('pddl.planning.domains.session.share');

// Generate classroom sessions
await vscode.commands.executeCommand('pddl.planning.domains.session.generateClassroom');

// Example: Load and work with Planning.Domains session
async function loadPlanningDomainsSession(sessionId: string) {
    // Load session by ID
    await vscode.commands.executeCommand('pddl.planning.domains.session.load');

    // User will be prompted to enter session ID
    // Alternatively, use URI scheme:
    // vscode://jan-dolejsi.pddl/planning.domains/session/<readOnlyHash>
    // vscode://jan-dolejsi.pddl/planning.domains/session/edit/<readWriteHash>

    // Work with files in session
    // Changes are tracked in Source Control view

    // Commit changes when ready
    await vscode.commands.executeCommand('pddl.planning.domains.session.commit');
}
```

--------------------------------

### Default POPF Planner Command Line Syntax in VS Code

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Configuring-the-PDDL-planner

This configuration specifies the default command-line syntax for the POPF planner when integrated with the VS Code PDDL extension. It shows how to use placeholders for the planner executable, options, domain, and problem files.

```bash
$(planner) $(options) $(domain) $(problem)
```

--------------------------------

### Initialize PDDL Predicates from JSON Drivers (Jinja2, Lisp)

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Templating-hints

This snippet shows how to initialize PDDL predicates like 'at' and 'available' based on driver data from a JSON object. It uses Jinja2 templating to iterate through drivers and conditionally set predicates based on their status. This is essential for setting up the initial state of a PDDL problem.

```Jinja2
;;(
    drivers
    {% for driver in data.drivers %}
    ; Driver: {{driver.name}}
        (at {{driver.name}} {{driver.location}})
        {% if driver.status == 'on-duty' %}
            (available {{driver.name}})
        {% endif %}
    {% endfor %}
;;)
```

```Lisp
;;(
    drivers
    ; Driver: driver1
        (at driver1 office)
            (available driver1)
    ; Driver: driver2
        (at driver2 home)
;;)
```

--------------------------------

### Configure Problem File Generation with Preprocessing Options

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This JSON configuration defines how PDDL problem files are generated. It specifies default domain and problem files, and an array of 'cases'. Each case can define a 'preProcess' object with options like 'kind' (nunjucks, jinja2, command, python), 'data', 'command', 'script', and 'args'. Relative paths are supported for data and script files.

```json
{
    "defaultDomain": "domain.pddl",
    "defaultProblem": "problem_template.pddl",
    "defaultOptions": "",
    "cases": [
        {
            "label": "Case #1",
            "preProcess": {
                "kind": "nunjucks",
                "data": "case1_data.json"
            }
        },
        {
            "label": "Case #1.1",
            "preProcess": {
                "kind": "jinja2",
                "data": "case1_data.json"
            }
        },
        {
            "label": "Case #2",
            "preProcess": {
                "kind": "command",
                "command": "myprogram.exe",
                "args": [
                    "case2_data.json",
                    "some_switch",
                    42
                ]
            }
        },
        {
            "label": "Case #3",
            "preProcess": {
                "kind": "python",
                "script": "../scripts/populate_template.py",
                "args": [
                    "case3_data.json"
                ]
            }
        }
    ]
)
```

--------------------------------

### Command-line Preprocessing for PDDL Problem Files

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This configuration demonstrates using an external command-line program for PDDL problem file generation. The specified 'command' is executed with provided 'args'. The program is expected to read the problem template from standard input and write the generated PDDL to standard output.

```json
{
    "kind": "command",
    "command": "myprogram.exe",
    "args": [
        "case2_data.json",
        "some_switch",
        42
    ]
}
```

--------------------------------

### Get Objects of a Specific Type (JavaScript)

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/How-to-implement-custom-plan-state-visualization

Given an `allObjects` map (which contains domain constants and problem objects), this code snippet retrieves all objects of a specified type, such as 'block'. It returns an array of strings representing the object names.

```javascript
allObjects.getTypeCaseInsensitive("block").getObjects()
```

--------------------------------

### Create PDDL Test Case Configuration JSON

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

Defines a PDDL test case configuration file in JSON format. This file specifies the default domain, default options, and a list of problem files to be tested. It can also include properties like 'expectedPlans' for assertions and 'options' for planner command-line arguments.

```json
{
    "defaultDomain": "StripsRover.pddl",
    "defaultOptions": "",
    "cases": [
        {"problem": "pfile1"},
        {"problem": "pfile2"},
        {"problem": "pfile3"}
    ]
}
```

--------------------------------

### PDDL Planning Service Integration (TypeScript)

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

Demonstrates how to initialize, run, and stop the PDDL planning service using the VS Code extension's API. It covers programmatic triggering of planning with specified domain and problem files, and handling potential errors during the process.

```typescript
import { Planning } from './planning/planning';
import { PlanningResult } from './planning/PlanningResult';

// Initialize planning with workspace and configuration
const planning = new Planning(codePddlWorkspace, pddlConfiguration, plannersConfiguration, context);

// Run planner on domain and problem files
await commands.executeCommand('pddl.planAndDisplayResult');

// Stop running planner
await commands.executeCommand('pddl.stopPlanner');

// Example: Programmatically trigger planning
async function executePlanner(domainUri: vscode.Uri, problemUri: vscode.Uri) {
    try {
        await vscode.commands.executeCommand(
            'pddl.planAndDisplayResult',
            domainUri,
            problemUri,
            workspace.getWorkspaceFolder(domainUri)?.uri.fsPath,
            '--options-for-planner'
        );
    } catch (error) {
        vscode.window.showErrorMessage(`Planning failed: ${error}`);
    }
}
```

--------------------------------

### Configure Custom Visualization File

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/How-to-implement-custom-plan-state-visualization

Specifies the JavaScript file to use for custom visualizations. This JSON configuration should be placed in a file named '<your_domain>.planviz.json' alongside your PDDL domain file.

```json
{
    "customVisualization": "blocksWorldViz.js"
}
```

--------------------------------

### VS Code PDDL: Configure Planner Command Line Setting

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Search-tree-debugger-API

Demonstrates how to configure the planner command-line syntax for sending search diagnostic data. The `$(port)` placeholder will be replaced with the actual port number.

```json
{
    "pddlSearchDebugger.plannerCommandLine": "/path/to/planner --search-debugger --port $(port)"
}
```

--------------------------------

### Integrate and Configure VAL Tools for PDDL

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This section demonstrates how to integrate and configure the VAL (PDDL validation) tools within VSCode. It includes commands to download VAL, set configuration paths for its executables, and validate PDDL plans. The configuration is applied globally using VSCode's workspace configuration API. It also includes a check to prompt the user to download VAL if it's not configured.

```typescript
// Download VAL tools
await vscode.commands.executeCommand('pddl.downloadVal');

// Configure VAL tools paths
const valConfig = {
    "pddl.validatorPath": "/usr/local/bin/Validate",
    "pddl.valStepPath": "/usr/local/bin/ValStep",
    "pddl.valueSeqPath": "/usr/local/bin/ValueSeq",
    "pddl.valVerbose": false
};

// Apply VAL configuration
async function configureValTools() {
    const config = workspace.getConfiguration('pddl');

    await config.update('validatorPath', '/usr/local/bin/Validate', ConfigurationTarget.Global);
    await config.update('valStepPath', '/usr/local/bin/ValStep', ConfigurationTarget.Global);
    await config.update('valueSeqPath', '/usr/local/bin/ValueSeq', ConfigurationTarget.Global);

    vscode.window.showInformationMessage('VAL tools configured successfully');
}

// Example: Validate plan with VAL
async function validatePlanWithVal(planPath: string) {
    const doc = await workspace.openTextDocument(planPath);
    await vscode.window.showTextDocument(doc);

    // Ensure VAL is configured
    const validatorPath = workspace.getConfiguration('pddl').get('validatorPath');
    if (!validatorPath) {
        const download = await vscode.window.showInformationMessage(
            'VAL validator not configured. Download now?',
            'Download', 'Cancel'
        );

        if (download === 'Download') {
            await vscode.commands.executeCommand('pddl.downloadVal');
        }
        return;
    }

    // Run validation
    await vscode.commands.executeCommand('pddl.plan.validate');
}

```

--------------------------------

### Run PDDL Tests using Test Explorer

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet demonstrates how to interact with the PDDL Test Explorer in VSCode. It covers creating a test manifest file and executing commands to run, refresh, and view reports for PDDL tests. Dependencies include the VSCode API and the 'path' module.

```typescript
import { PTestExplorer } from './ptest/PTestExplorer';
import { Test } from './ptest/Test';

// Create test manifest (.ptest.json)
const testManifest = {
    "defaultDomain": "domain.pddl",
    "defaultOptions": "--search \"astar(lmcut())\"",
    "cases": [
        {
            "problem": "problem1.pddl",
            "expectedPlans": 1
        },
        {
            "problem": "problem2.pddl",
            "expectedPlans": 1,
            "options": "--search \"astar(hmax())\""
        },
        {
            "label": "Templated problem",
            "problem": "problem_template.pddl",
            "preProcess": {
                "kind": "nunjucks",
                "data": "data.json"
            },
            "expectedPlans": 1
        }
    ]
};

// Run all tests
await vscode.commands.executeCommand('pddl.tests.runAll');

// Run specific test
await vscode.commands.executeCommand('pddl.tests.run', testNode);

// Refresh test explorer
await vscode.commands.executeCommand('pddl.tests.refresh');

// Example: Create and run PDDL tests
async function createAndRunTests(workspaceFolder: vscode.WorkspaceFolder) {
    const testManifestPath = path.join(workspaceFolder.uri.fsPath, 'tests.ptest.json');

    await workspace.fs.writeFile(
        Uri.file(testManifestPath),
        Buffer.from(JSON.stringify(testManifest, null, 2))
    );

    // Refresh test explorer to pick up new manifest
    await vscode.commands.executeCommand('pddl.tests.refresh');

    // Run all tests
    await vscode.commands.executeCommand('pddl.tests.runAll');

    // View test report
    await vscode.commands.executeCommand('pddl.tests.report.view');
}
```

--------------------------------

### Configure Custom PDDL Plan Visualization

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet shows how to set up custom visualization for PDDL plans by defining a configuration object and a JavaScript file for the visualization logic. It handles excluding certain actions and ignoring parameters, and writes these configurations to files. Dependencies include VSCode's workspace API for file operations.

```typescript
// Create custom visualization (blocksWorldViz.json)
const planVizConfig = {
    "customVisualization": "blocksWorldViz.js",
    "excludeActions": [
        "^internal_",
        "_cleanup$"
    ],
    "ignoreActionParameters": [
        {
            "action": "^move",
            "parameterPattern": "^(intermediate|temp)$"
        }
    ]
};

// Custom visualization implementation (blocksWorldViz.js)
const customVisualization = `
/**
 * Visualize plan as HTML
 * @param {Plan} plan - the plan to visualize
 * @param {number} width - display width in pixels
 * @returns {string} HTML content
 */
function visualizePlanHtml(plan, width) {
    const height = 250;
    let html = '<div style="font-family: monospace;">';

    plan.steps.forEach((step, index) => {
        html += `<div>Step ${index + 1}: ${step.fullActionName} at ${step.time}</div>`;
    });

    html += '</div>';
    return html;
}

/**
 * Visualize final state in DOM
 * @param {HTMLDivElement} planVizDiv - container element
 * @param {Plan} plan - the plan
 * @param {Array} finalState - array of {variableName, value} objects
 * @param {number} displayWidth - width in pixels
 */
function visualizeStateInDiv(planVizDiv, plan, finalState, displayWidth) {
    const valueMap = new Map(finalState.map(i => [i.variableName, i.value]));

    planVizDiv.innerHTML = '<h3>Final State</h3>';
    const list = document.createElement('ul');

    for (const [varName, value] of valueMap) {
        const item = document.createElement('li');
        item.textContent = `${varName}: ${value}`;
        list.appendChild(item);
    }

    planVizDiv.appendChild(list);
}

module.exports = {
    visualizePlanHtml: visualizePlanHtml,
    visualizeStateInDiv: visualizeStateInDiv
};
`;

// Example: Configure custom visualization
async function setupCustomVisualization(domainPath: string) {
    const domainDir = path.dirname(domainPath);
    const domainName = path.basename(domainPath, '.pddl');

    // Write planviz config
    const configPath = path.join(domainDir, `${domainName}.planviz.json`);
    await workspace.fs.writeFile(
        Uri.file(configPath),
        Buffer.from(JSON.stringify(planVizConfig, null, 2))
    );

    // Write visualization script
    const scriptPath = path.join(domainDir, 'blocksWorldViz.js');
    await workspace.fs.writeFile(
        Uri.file(scriptPath),
        Buffer.from(customVisualization)
    );
}

```

--------------------------------

### Access Domain and Problem Objects (JavaScript)

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/How-to-implement-custom-plan-state-visualization

Retrieves all PDDL constants and objects from the domain and problem files by merging them. It includes checks to ensure `plan.problem` and `plan.domain` are defined before accessing their methods.

```javascript
// get all domain constants plus problem objects
   const allObjects = plan.problem && plan.problem.getObjectsTypeMap()
      && plan.domain && plan.domain.getConstants()
      && plan.domain.getConstants().merge(plan.problem.getObjectsTypeMap());
```

--------------------------------

### Configure PDDL4J Java Agent Planner in VS Code

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Configuring-the-PDDL-planner

This configuration allows using the PDDL4J planner via a Java agent. It specifies the path to the PDDL4J JAR file and sets JVM arguments for memory allocation. The syntax element defines how planner arguments are passed.

```json
{
    "title": "PDDL4J Agent",
    "kind": "JAVA_JAR",
    "path": "java -javaagent:d:/tools/pddl4j/pddl4j-3.5.0.jar -server -Xms2048m -Xmx2048m fr.uga.pddl4j.planners.hsp.HSP",
    "syntax": "$(planner) $(options) -o $(domain) -f $(problem)"
}
```

--------------------------------

### Configure Plan Visualization Exclusions (JSON)

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This JSON configuration file allows users to specify actions to be excluded from plan visualization. It supports exact action names and regular expression patterns for exclusion. Ensure backslashes in regex patterns are doubled to comply with JSON syntax.

```json
{
    "excludeActions": [
        "action-to-be-hidden",
        "^prefix_",
        "suffix$"
    ]
}
```

--------------------------------

### POST /state/initial

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Search-tree-debugger-API

Adds the initial state of the search tree.

```APIDOC
## POST /state/initial

### Description
Adds the initial state into the search tree.

### Method
POST

### Endpoint
/state/initial

### Request Body
- **id** (string) - Required - Unique identifier for the state.
- **parentId** (string) - Optional - The ID of the parent state. Should be null for the initial state.
- **g** (number) - Required - The cost to reach this state from the initial state.
- **earliestTime** (number) - Required - The earliest possible time this state can be reached.

### Request Example
```json
{
    "id": "0",
    "parentId": null,
    "g": 0,
    "earliestTime": 0.001000
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Initial state added successfully."
}
```
```

--------------------------------

### Configure PDDL Parser Executable for VAL

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Configuring-the-PDDL-parser

Configures the PDDL extension to use the VAL parser executable. This requires specifying the parser executable's name and passing the domain and problem files as command-line arguments.

```plaintext
pddlParser.executableOrService: Parser.exe
pddlParser.executableOptions: $(domain) $(problem)
```

--------------------------------

### Custom Planner Output Format Requirements

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Configuring-the-PDDL-planner

This outlines the expected output format for custom PDDL planners to be recognized by the VS Code extension. It specifies how cost and states evaluated should be indicated, and how actions (instantaneous and durative) should be represented, including optional duration and action cost for durative actions.

```text
; some other output that is not part of the plan
***cost***: number
***States evaluated***: number
time: (some-instantaneous-action-name args)
time: (some-durative-action-name args) [duration]
time: (some-durative-action-name args) [D:<duration>; C:<actionCost>]
; some other output that separates plans in the output
```

--------------------------------

### Jinja2 Templating for PDDL Problem Files

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This configuration indicates the use of the Jinja2 templating engine for PDDL problem file generation. Similar to Nunjucks, it requires a 'data' file (JSON) for populating the template. Jinja2 requires invoking Python, which may introduce a slight performance overhead compared to Nunjucks.

```json
{
    "kind": "jinja2",
    "data": "case1_data.json"
}
```

--------------------------------

### Python Script for PDDL Problem File Generation

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This outlines the configuration for using a Python script to preprocess PDDL problem files. The extension executes the specified Python script, piping the problem template to its standard input and reading the generated PDDL from its standard output. The script can use provided JSON data or other sources for manipulation.

```json
{
    "kind": "python",
    "script": "../scripts/populate_template.py",
    "args": [
        "case3_data.json"
    ]
}
```

--------------------------------

### Configure PDDL Solver Service URL in VS Code Settings

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This JSON configuration specifies the PDDL solver service URL within the VS Code workspace settings. It is used by the 'solver' plugin to connect to a local or remote solver. The 'kind' property indicates the type of planner, 'url' is the service endpoint, and 'title' is a human-readable name. 'canConfigure' determines if the planner can be configured via the UI.

```json
{
    "pddl.planners": [
        {
            "kind": "SERVICE_SYNC",
            "url": "http://localhost:12345/solve",
            "title": "http://localhost:12345/solve",
            "canConfigure": true
        }
    ]
}
```

--------------------------------

### Validate and Convert PDDL Plans

Source: https://context7.com/jan-dolejsi/vscode-pddl/llms.txt

This snippet shows how to use VSCode commands for PDDL plan manipulation. It covers validating plan files, converting between plan and happenings formats, previewing plan visualizations, and normalizing plans for comparison. The primary dependency is the VSCode API.

```typescript
// Validate plan file
await vscode.commands.executeCommand('pddl.plan.validate');

// Convert plan to happenings format
await vscode.commands.executeCommand('pddl.convertPlanToHappenings');

// Convert happenings back to plan
await vscode.commands.executeCommand('pddl.convertHappeningsToPlan');

// Preview plan visualization
await vscode.commands.executeCommand('pddl.plan.preview');

// Normalize and compare two plans
await vscode.commands.executeCommand('pddl.plan.compareNormalized');

// Example: Validate and visualize plan
async function validateAndVisualizePlan(planUri: vscode.Uri) {
    try {
        // First validate the plan
        const doc = await workspace.openTextDocument(planUri);
        await vscode.window.showTextDocument(doc);

        await vscode.commands.executeCommand('pddl.plan.validate');

        // If validation passes, preview the plan
        await vscode.commands.executeCommand('pddl.plan.preview');

        // Generate plan report
        await vscode.commands.executeCommand('pddl.planReport');
    } catch (error) {
        vscode.window.showErrorMessage(`Plan validation failed: ${error}`);
    }
}
```

--------------------------------

### POST /plan

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Search-tree-debugger-API

Renders the plan head of a given state on the search tree in green.

```APIDOC
## POST /plan

### Description
This accepts the same payload as the `/state` endpoint. The planhead of the supplied state is rendered on the tree in green.

### Method
POST

### Endpoint
/plan

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier for the state.
- **parentId** (string) - Required - The ID of the parent state.
- **g** (number) - Required - The cost to reach this state from the initial state.
- **earliestTime** (number) - Required - The earliest possible time this state can be reached.
- **appliedAction** (object) - Optional - Information about the action applied to reach this state.
    - **actionName** (string) - Required - The name of the action, including arguments.
    - **shotCounter** (number) - Optional - For multi-shot actions, the index of this application in this search branch.
    - **earliestTime** (number) - Required - The earliest time the action can start.
    - **kind** (string) - Required - Type of action application (e.g., "START", "END", "INSTANTANEOUS", "TIMED").
- **planHead** (array) - Required - The sequence of actions forming the plan head.
    - (object) - Represents an action in the plan head.
        - **actionName** (string) - Required - The name of the action, including arguments.
        - **shotCounter** (number) - Optional - For multi-shot actions, the index of this application in this search branch.
        - **earliestTime** (number) - Required - The earliest time the action can start.
        - **kind** (string) - Required - Type of action application (e.g., "START", "END", "INSTANTANEOUS", "TIMED").

### Request Example
```json
{
    "id": "1",
    "parentId": "0",
    "g": 1,
    "earliestTime": 0.002000,
    "appliedAction": {
        "actionName": "action-name arg1 arg2",
        "shotCounter": 0,
        "earliestTime": 0.002000,
        "kind": "START"
    },
    "planHead": [
        {
            "actionName": "action-name arg1 arg2",
            "shotCounter": 0,
            "earliestTime": 0.002000,
            "kind": "START"
        }
    ]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Plan head rendered successfully."
}
```
```

--------------------------------

### Nunjucks Templating for PDDL Problem Files

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This configuration specifies the use of the Nunjucks templating engine for generating PDDL problem files. The 'data' parameter points to a JSON file containing the data to be used with the Nunjucks template. Nunjucks runs natively in JavaScript, ensuring efficient file generation.

```json
{
    "kind": "nunjucks",
    "data": "case1_data.json"
}
```

--------------------------------

### VS Code PDDL Snippets

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

These are prefixes that trigger the insertion of common PDDL structures within the VS Code editor. They facilitate faster creation of domain and problem files.

```plaintext
domain
action
action-durative
problem
```

--------------------------------

### Configure Ignored Action Parameters for Plan Visualization

Source: https://github.com/jan-dolejsi/vscode-pddl/blob/master/README.md

This JSON configuration allows you to specify action parameters that should be ignored during swim-lane plan visualization. This helps to declutter diagrams by omitting parameters that do not significantly impact the action's context. The configuration uses regular expressions to match action names and parameter patterns.

```json
{
    "ignoreActionParameters": [
        {
            "action": "^move",
            "parameterPattern": "^(to|from)$"
        },
        {
            "action": ".+",
            "parameterPattern": "_reserved$"
        }
    ]
}
```

--------------------------------

### Configure PDDL Parser Executable for PDDL4J

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/Configuring-the-PDDL-parser

Configures the PDDL extension to use the PDDL4J parser. This involves specifying the Java executable and providing command-line arguments to load the PDDL4J parser and process domain and problem files.

```plaintext
pddlParser.executableOrService: java
pddlParser.executableOptions: -javaagent:c:/tools/pddl4j/pddl4j-3.5.0.jar -server -Xms2048m -Xmx2048m fr.uga.pddl4j.parser.Parser -o $(domain) -f $(problem)
```

--------------------------------

### Extract Block Names (JavaScript)

Source: https://github.com/jan-dolejsi/vscode-pddl/wiki/How-to-implement-custom-plan-state-visualization

Extracts block names either from the `allObjects` map if available, or by iterating through the plan steps and collecting unique object names. The extracted names are then sorted lexicographically.

```javascript
   /** @type {string[]} block names */
   const blocks = allObjects ? 
      allObjects.getTypeCaseInsensitive("block").getObjects() :
      [...new Set(plan.steps.map(s => s.getObjects()).reduce((prev, cur) => prev.concat(cur)))]

   const sortedBlocks = blocks.sort();

```