Simple command-line agent harness
- Python 100%
|
Chris Webb
b0955d369d
Tighten up key-binding corner cases in ua.bash
Suspending a foreground job (like an editor or agent) run from a readline binding correctly returns you to the shell with the job stopped, but the terminal state can be corrupted. This is really a bash bug, but save and restore the state to guard against it anyway. Delete the temporary file in readline-edit if we restored READLINE_LINE from it. If the editor was suspended, leave the file intact and use eval to make sure its path is explicit in the description of the stopped job. |
||
|---|---|---|
| examples | Tighten up key-binding corner cases in ua.bash | |
| COPYING | Import initial prototype | |
| README | Make reasoning effort adjustable | |
| ua | Incorporate feedback from Claude Fable 5 | |
ua == ua is a minimal agent harness, providing a command-line interface to a large language model accessed through an Open Responses API, and allowing it to access local tools including a shell. Installation and configuration ------------------------------ A single Python 3.12+ script 'ua' is provided. Ensure the #! path is correct for your system before copying it to a directory on your path. The tool has no dependencies beyond the standard library. It is configured through the environment. Set API, KEY and MODEL to the endpoint, bearer key and model ID, e.g. export API=https://openrouter.ai/api/v1/responses export KEY=sk-or-v1-xxx export MODEL=anthropic/claude-opus-4.6 ua appends to an NDJSON conversation log in LOG, defaulting to 'ua.log'. If LOG is an empty string, /dev/null is used and the log is not locked. If set, REASONING overrides the default reasoning effort for the model. The shell tool is built-in and passes commands from the model to SHELL on stdin. Change SHELL to wrap commands before execution: to authorise them, drop to a less privileged user, sandbox within more restrictive namespaces, or even run them on a different host. For instance, set SHELL to the examples/confirm wrapper to preview and confirm commands on the terminal before running them with bash. If SHELL is empty or unset, the shell tool is disabled. A directory of additional self-describing tool executables can be given in TOOLS. Each of these should read JSON input on stdin then produce JSON output on stdout. If stdin is empty, they should instead print their JSON tool schema. User input ---------- 'ua system' and 'ua user' add a new system or user message to the log. If stdin is a terminal, ua will get the message text via a text editor; otherwise, it will read it directly from stdin. An example system message explaining how the shell tool might be used is provided in examples/system.txt. Agent loop ---------- 'ua agent' repeatedly calls the model, streaming assistant messages to stdout and executing any tool calls. All generated items are appended to the log. The loop terminates once the model has returned a finished response to the user. Running 'ua' without arguments is a shortcut for 'ua user agent'. It takes a message from the user then immediately invites the model to reply. Other actions ------------- 'ua abort' aborts any pending function calls in the log. This is useful if you want to interrupt the model to provide updated instructions, and when prompting the model to fork copies of its own state. 'ua recap' will print the message history from the log to stdout. Copying ------- This software was written by Chris Webb <chris@arachsys.com> and is distributed as Free Software under the terms of the MIT license in COPYING.