initial implementation

readme.md

@@ -0,0 +1,27 @@
+# Gral
+
+Clone the repository, then install with `npm install -g .`.
+
+Usage: `gral <function> -p <prompt>`, or pass a file as a prompt instead with the `-f <prompt-file>` option.
+
+Gral uses the `.gral` directory from the working path for its configuration. The horde connection uses the 'host' and 'token' values stored in `.gral/config.json`, or loads them from the environment if not present.
+
+Every javascript module in `.gral/functions` exports a default function, it receives a single prompt string argument. These are the functions invoked by the gral command, you can list them with `gral -l`.
+
+The `Gral` global is available in the function module scopes, and exposes:
+- `path`: the working directory
+- `run`: the run command for sending prompts to agents
+
+The `run` function is the main harness functionality, it prompts agents with a tool bundle restricted based on the arguments.
+- `agentId`: the target agent that will process the prompt
+- `instruction` `input` and `messages`: these are sent to the horde 'prompt' action as the main input for the agent
+- `read` and `write`: list of files and directories open for access during the run. `null` and `true` means allow all, `false` and `[]` means allow none.
+- `open`: files and directories to open beforehand and send as context for the run
+- `tools`: tools to pass the agent
+- `defaultTools`: list of default tools to include in the list, special values are the same as read and write
+
+Default tools include these:
+- `read-file`: read a file, max size of 1kb, with optional `lineStart` and `lineEnd` arguments
+- `write-file`: write the entire content of a file, no write limit
+- `update-file`: accepts `search` and `replace` arguments, and an optional `global` argument
+- `list-dir`: lists the contents of a directory (directories are distinguished by their '/' prefix)