nakedagent 0.1.0__tar.gz

nakedagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reuben Bowlby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nakedagent-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: nakedagent
+Version: 0.1.0
+Summary: A coding agent with zero runtime dependencies. Stdlib-only Python.
+Author-email: Reuben Bowlby <reuben@hummbl.io>
+Maintainer-email: "HUMMBL, LLC" <reuben@hummbl.io>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hummbl-io/nakedagent
+Project-URL: Homepage, https://github.com/hummbl-io/nakedagent
+Project-URL: Documentation, https://github.com/hummbl-io/nakedagent#readme
+Project-URL: Issues, https://github.com/hummbl-io/nakedagent/issues
+Project-URL: Changelog, https://github.com/hummbl-io/nakedagent/releases
+Keywords: coding-agent,zero-dependencies,stdlib-only,llm,autonomous-agents,software-engineering,replay,mealy-machine,ollama
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nakedagent
+
+A coding agent with **zero runtime dependencies**. `pip install`-free by
+construction: `python -m nakedagent` runs on a stock Python 3.10+ interpreter,
+nothing else.
+
+```
+$ python -m nakedagent
+nakedagent -- workspace: /home/you/myproject -- model: qwen2.5-coder:7b
+Ctrl-D to exit.
+
+> add a .gitignore for a Python project
+```
+
+## Why
+
+Every other agent in this space — gptme, aider, OpenHands, langchain-based
+tools — pulls in 20-40+ packages: HTTP clients, CLI-formatting libraries,
+provider SDKs, telemetry. That's not a criticism of them; those dependencies
+buy real capability (multi-provider abstraction, rich terminal rendering,
+robust malformed-output recovery). But it also means every install inherits
+whatever CVEs are sitting in that dependency tree, and updating any one
+package can break the agent.
+
+nakedagent takes the other side of that trade on purpose: `urllib` + `json` +
+`subprocess` + `re`, all from the standard library, are enough to drive a
+local model through a working tool-use loop. No supply chain, because there
+is no supply.
+
+## What you get for that
+
+- **Tools**: `shell`, `read`, `write`, `patch` (search/replace edits, aider's
+  simplest edit format). That's the whole *foundation* tool surface.
+  `shell` is confirmation-first in interactive mode and requires `--allow-shell`
+  in non-interactive mode, with optional command filtering via
+  `--shell-allowlist`.
+- **Model backend**: [Ollama](https://ollama.com) by default — local-first,
+  no API key required to try it. For models too large to run locally,
+  `--api openai` speaks the OpenAI-compatible format that hosted APIs,
+  vLLM/LM Studio and gateways share (see below).
+- **Tool-call format**: the model writes a fenced code block whose language
+  tag is the tool name; nakedagent parses it out of the response text after
+  each turn. Works with any model that can write a code fence — no dependency
+  on a provider's native function-calling API.
+- **Plugins**: drop a `.py` file in `.nakedagent/plugins/` (repo-local,
+  requires `--trust-workspace-plugins`) or `~/.nakedagent/plugins/`
+  (user-global, always loaded) that defines a `TOOLS` dict (add or
+  override tools) and/or a `DISABLE` list (remove tools entirely — e.g. a
+  read-only agent disables `shell` and `write`). Each tool carries a `.usage`
+  attribute that controls its prompt example, so a plugin replacing a tool
+  replaces its syntax too. No registration, no framework — see
+  [`DOCTRINE.md`](DOCTRINE.md) for the omakase framing. Repo-local plugins
+  are off by default because they execute with your privileges — only pass
+  the flag in workspaces you trust.
+
+See [`docs/architecture/architecture.md`](docs/architecture/architecture.md) for how the loop and tool
+parser work, including what was learned from reading gptme's and aider's
+actual source before writing this.
+
+## Quick start
+
+```bash
+git clone https://github.com/hummbl-io/nakedagent.git
+cd nakedagent
+ollama pull qwen2.5-coder:7b   # or any model you like
+python -m nakedagent           # interactive
+python -m nakedagent "explain what this repo does"   # one-shot
+```
+
+### Larger models
+
+Small local models get the loop running; bigger models make it good. Point
+nakedagent at any OpenAI-compatible server. The key comes from an
+environment variable (`--api-key-env`, default `OPENAI_API_KEY`), never a flag:
+
+```bash
+# hosted API
+OPENAI_API_KEY=... python -m nakedagent --api openai --host https://api.openai.com/v1 -m <model>
+
+# self-hosted (vLLM, LM Studio) — no key needed
+python -m nakedagent --api openai --host http://localhost:8000/v1 -m <model>
+```
+
+## Shell safety for automation
+
+For one-shot runs and other non-interactive use-cases, the shell tool is denied
+unless explicit shell allowances are provided:
+
+```bash
+python -m nakedagent "run project checks" --allow-shell --shell-allowlist "git status" --shell-allowlist "ls"
+```
+
+`--shell-allowlist` is prefix-based. If you pass `--allow-shell` with an empty
+allowlist, all non-interactive shell commands are blocked.
+
+No `pip install` step. That's not an oversight — `nakedagent/` only imports
+the standard library, so running it in place works.
+
+## Provable execution: event log + replay
+
+One-shot runs can go through the functional lane — the agent is a pure Mealy
+machine (`functional.agent_reducer`: `(state, event) -> (state, actions)`),
+and a thin driver (`driver.py`) performs the actual model/tool IO while
+appending every event to a JSONL log:
+
+```bash
+python -m nakedagent "add a .gitignore" --event-log run.jsonl
+```
+
+Each logged event carries the Merkle state hash *after* that transition, so
+the trace is a tamper-evident receipt. Replay reconstructs the run with zero
+model calls and verifies the whole chain:
+
+```bash
+python -m nakedagent.replay run.jsonl
+# PASS run.jsonl: verified 5 events (1 tool results); final hash 6d1e0965…
+```
+
+## Status
+
+MVP. Two wire formats (Ollama native + OpenAI-compatible), four foundation
+tools, no streaming. The plugin
+seam is the one extension surface — see [`DOCTRINE.md`](DOCTRINE.md).
+Went through two independent peer reviews (headless GLM-5.2, and a
+separately-running devin session, both 2026-09-09) before this first push —
+between them they found five real bugs, all fixed with regression tests,
+documented in [`docs/architecture/architecture.md`](docs/architecture/architecture.md) alongside what's
+still genuinely not here and why.
+
+## Research & Citation
+
+If you use nakedagent in academic research or want to study its architecture, please cite our research paper:
+
+> Reuben Bowlby, **"NakedAgent: A Zero-Dependency Coding Agent Architecture via Standard-Library Primitives and Provable Replay"**, HUMMBL Research, Zenodo Preprint, 2026.
+
+Preprint PDF and LaTeX sources are available under [`paper/`](paper/). For machine-readable citation metadata, see [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nakedagent-0.1.0/README.md

@@ -0,0 +1,140 @@
+# nakedagent
+
+A coding agent with **zero runtime dependencies**. `pip install`-free by
+construction: `python -m nakedagent` runs on a stock Python 3.10+ interpreter,
+nothing else.
+
+```
+$ python -m nakedagent
+nakedagent -- workspace: /home/you/myproject -- model: qwen2.5-coder:7b
+Ctrl-D to exit.
+
+> add a .gitignore for a Python project
+```
+
+## Why
+
+Every other agent in this space — gptme, aider, OpenHands, langchain-based
+tools — pulls in 20-40+ packages: HTTP clients, CLI-formatting libraries,
+provider SDKs, telemetry. That's not a criticism of them; those dependencies
+buy real capability (multi-provider abstraction, rich terminal rendering,
+robust malformed-output recovery). But it also means every install inherits
+whatever CVEs are sitting in that dependency tree, and updating any one
+package can break the agent.
+
+nakedagent takes the other side of that trade on purpose: `urllib` + `json` +
+`subprocess` + `re`, all from the standard library, are enough to drive a
+local model through a working tool-use loop. No supply chain, because there
+is no supply.
+
+## What you get for that
+
+- **Tools**: `shell`, `read`, `write`, `patch` (search/replace edits, aider's
+  simplest edit format). That's the whole *foundation* tool surface.
+  `shell` is confirmation-first in interactive mode and requires `--allow-shell`
+  in non-interactive mode, with optional command filtering via
+  `--shell-allowlist`.
+- **Model backend**: [Ollama](https://ollama.com) by default — local-first,
+  no API key required to try it. For models too large to run locally,
+  `--api openai` speaks the OpenAI-compatible format that hosted APIs,
+  vLLM/LM Studio and gateways share (see below).
+- **Tool-call format**: the model writes a fenced code block whose language
+  tag is the tool name; nakedagent parses it out of the response text after
+  each turn. Works with any model that can write a code fence — no dependency
+  on a provider's native function-calling API.
+- **Plugins**: drop a `.py` file in `.nakedagent/plugins/` (repo-local,
+  requires `--trust-workspace-plugins`) or `~/.nakedagent/plugins/`
+  (user-global, always loaded) that defines a `TOOLS` dict (add or
+  override tools) and/or a `DISABLE` list (remove tools entirely — e.g. a
+  read-only agent disables `shell` and `write`). Each tool carries a `.usage`
+  attribute that controls its prompt example, so a plugin replacing a tool
+  replaces its syntax too. No registration, no framework — see
+  [`DOCTRINE.md`](DOCTRINE.md) for the omakase framing. Repo-local plugins
+  are off by default because they execute with your privileges — only pass
+  the flag in workspaces you trust.
+
+See [`docs/architecture/architecture.md`](docs/architecture/architecture.md) for how the loop and tool
+parser work, including what was learned from reading gptme's and aider's
+actual source before writing this.
+
+## Quick start
+
+```bash
+git clone https://github.com/hummbl-io/nakedagent.git
+cd nakedagent
+ollama pull qwen2.5-coder:7b   # or any model you like
+python -m nakedagent           # interactive
+python -m nakedagent "explain what this repo does"   # one-shot
+```
+
+### Larger models
+
+Small local models get the loop running; bigger models make it good. Point
+nakedagent at any OpenAI-compatible server. The key comes from an
+environment variable (`--api-key-env`, default `OPENAI_API_KEY`), never a flag:
+
+```bash
+# hosted API
+OPENAI_API_KEY=... python -m nakedagent --api openai --host https://api.openai.com/v1 -m <model>
+
+# self-hosted (vLLM, LM Studio) — no key needed
+python -m nakedagent --api openai --host http://localhost:8000/v1 -m <model>
+```
+
+## Shell safety for automation
+
+For one-shot runs and other non-interactive use-cases, the shell tool is denied
+unless explicit shell allowances are provided:
+
+```bash
+python -m nakedagent "run project checks" --allow-shell --shell-allowlist "git status" --shell-allowlist "ls"
+```
+
+`--shell-allowlist` is prefix-based. If you pass `--allow-shell` with an empty
+allowlist, all non-interactive shell commands are blocked.
+
+No `pip install` step. That's not an oversight — `nakedagent/` only imports
+the standard library, so running it in place works.
+
+## Provable execution: event log + replay
+
+One-shot runs can go through the functional lane — the agent is a pure Mealy
+machine (`functional.agent_reducer`: `(state, event) -> (state, actions)`),
+and a thin driver (`driver.py`) performs the actual model/tool IO while
+appending every event to a JSONL log:
+
+```bash
+python -m nakedagent "add a .gitignore" --event-log run.jsonl
+```
+
+Each logged event carries the Merkle state hash *after* that transition, so
+the trace is a tamper-evident receipt. Replay reconstructs the run with zero
+model calls and verifies the whole chain:
+
+```bash
+python -m nakedagent.replay run.jsonl
+# PASS run.jsonl: verified 5 events (1 tool results); final hash 6d1e0965…
+```
+
+## Status
+
+MVP. Two wire formats (Ollama native + OpenAI-compatible), four foundation
+tools, no streaming. The plugin
+seam is the one extension surface — see [`DOCTRINE.md`](DOCTRINE.md).
+Went through two independent peer reviews (headless GLM-5.2, and a
+separately-running devin session, both 2026-09-09) before this first push —
+between them they found five real bugs, all fixed with regression tests,
+documented in [`docs/architecture/architecture.md`](docs/architecture/architecture.md) alongside what's
+still genuinely not here and why.
+
+## Research & Citation
+
+If you use nakedagent in academic research or want to study its architecture, please cite our research paper:
+
+> Reuben Bowlby, **"NakedAgent: A Zero-Dependency Coding Agent Architecture via Standard-Library Primitives and Provable Replay"**, HUMMBL Research, Zenodo Preprint, 2026.
+
+Preprint PDF and LaTeX sources are available under [`paper/`](paper/). For machine-readable citation metadata, see [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nakedagent-0.1.0/nakedagent/__init__.py

@@ -0,0 +1,3 @@
+"""nakedagent: a coding agent with zero runtime dependencies."""
+
+__version__ = "0.1.0"

nakedagent-0.1.0/nakedagent/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

nakedagent-0.1.0/nakedagent/cli.py

@@ -0,0 +1,196 @@
+"""nakedagent -- a zero-dependency terminal coding agent."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .llm import APIS, DEFAULT_API_KEY_ENV, DEFAULT_HOST, LLMError
+from .loop import run, run_interactive
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="nakedagent", description=__doc__)
+    p.add_argument("prompt", nargs="?", help="run once with this prompt, then exit")
+    p.add_argument("-m", "--model", default="qwen2.5-coder:7b", help="model name or Ollama tag")
+    p.add_argument("-w", "--workspace", type=Path, default=Path.cwd())
+    p.add_argument(
+        "--host",
+        default=None,
+        help=(
+            f"model server URL (default: {DEFAULT_HOST} for ollama; required for "
+            "--api openai, including the version path, e.g. https://api.openai.com/v1)"
+        ),
+    )
+    p.add_argument(
+        "--api",
+        choices=APIS,
+        default="ollama",
+        help="wire format: ollama (local, default) or openai (any OpenAI-compatible server)",
+    )
+    p.add_argument(
+        "--api-key-env",
+        default=DEFAULT_API_KEY_ENV,
+        metavar="VAR",
+        help=(
+            "environment variable holding the API key for --api openai "
+            f"(default: {DEFAULT_API_KEY_ENV}); the key itself is never a flag"
+        ),
+    )
+    p.add_argument(
+        "--allow-shell",
+        action="store_true",
+        help="Allow shell tool execution in non-interactive contexts.",
+    )
+    p.add_argument(
+        "--shell-allowlist",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help=(
+            "Allowed shell command prefixes when --allow-shell is set. "
+            "Repeatable. Example: --shell-allowlist 'git status' "
+            "--shell-allowlist 'ls'"
+        ),
+    )
+    p.add_argument(
+        "--shell-timeout",
+        type=int,
+        default=120,
+        help="Timeout in seconds for shell tool execution.",
+    )
+    p.add_argument(
+        "--trust-plugins",
+        action="store_true",
+        help=(
+            "Load <workspace>/.nakedagent/plugins/*.py at startup. "
+            "Disabled by default to prevent arbitrary code execution on "
+            "untrusted repositories. Alias of --trust-workspace-plugins."
+        ),
+    )
+    p.add_argument(
+        "--trust-workspace-plugins",
+        action="store_true",
+        help=(
+            "Load <workspace>/.nakedagent/plugins/*.py at startup. Off by "
+            "default: workspace plugins are repo-controlled code running with "
+            "your privileges. Only set this in workspaces you trust. "
+            "User-global ~/.nakedagent/plugins/ always loads."
+        ),
+    )
+    p.add_argument(
+        "--event-log",
+        type=Path,
+        metavar="PATH",
+        help=(
+            "Run through the functional driver and append every agent event "
+            "to a JSONL log at PATH. One-shot mode only. Verify with "
+            "`python -m nakedagent.replay PATH`."
+        ),
+    )
+    p.add_argument(
+        "--resume",
+        type=Path,
+        metavar="PATH",
+        help=(
+            "Resume a suspended event log at PATH: replay-verify the recorded "
+            "prefix, then feed PROMPT as the human verdict that lifts the "
+            "suspension. PATH is reused as the event log — the suspended "
+            "trailer is replaced, the Merkle chain continues."
+        ),
+    )
+    p.add_argument("--version", action="version", version=__version__)
+    args = p.parse_args(argv)
+
+    workspace = args.workspace.resolve()
+    shell_allowlist = tuple(
+        pattern.strip() for pattern in args.shell_allowlist if pattern.strip()
+    )
+    if args.shell_timeout <= 0:
+        print("error: --shell-timeout must be greater than 0", file=sys.stderr)
+        return 1
+    if args.event_log and not args.prompt:
+        print("error: --event-log requires a one-shot prompt", file=sys.stderr)
+        return 1
+    if args.resume and not args.prompt:
+        print("error: --resume requires PROMPT as the verdict input", file=sys.stderr)
+        return 1
+    if args.resume and args.event_log and args.resume != args.event_log:
+        print("error: --resume reuses the same path as --event-log; pass only --resume", file=sys.stderr)
+        return 1
+    host = args.host
+    if host is None:
+        if args.api != "ollama":
+            # No default: silently sending a prompt (and a key) to a server
+            # the user didn't name is worse than asking.
+            print("error: --api openai needs --host (e.g. https://api.openai.com/v1)", file=sys.stderr)
+            return 1
+        host = DEFAULT_HOST
+    llm_options = {}
+    if args.api != "ollama":
+        llm_options = {"api": args.api, "api_key_env": args.api_key_env}
+    # Plugin trust: two flag spellings, one opt-in. `trust_plugins` always
+    # rides along; `trust_workspace_plugins` is forwarded only when a trust
+    # flag was actually given -- downstream defaults govern otherwise.
+    plugin_trust: dict = {"trust_plugins": args.trust_plugins}
+    if args.trust_plugins or args.trust_workspace_plugins:
+        plugin_trust["trust_workspace_plugins"] = args.trust_workspace_plugins
+    try:
+        if args.prompt:
+            if args.event_log or args.resume:
+                # Deferred import keeps `nakedagent.driver.run_functional`
+                # patchable at call time (the CLI tests mock it there).
+                from .driver import run_functional
+
+                run_functional(
+                    args.prompt,
+                    args.model,
+                    workspace,
+                    host,
+                    event_log_path=args.resume or args.event_log,
+                    allow_shell=args.allow_shell,
+                    shell_allowlist=shell_allowlist,
+                    shell_timeout=args.shell_timeout,
+                    llm_options=llm_options,
+                    resume_from=args.resume,
+                    **plugin_trust,
+                )
+            else:
+                run(
+                    args.prompt,
+                    args.model,
+                    workspace,
+                    host,
+                    allow_shell=args.allow_shell,
+                    shell_allowlist=shell_allowlist,
+                    shell_timeout=args.shell_timeout,
+                    llm_options=llm_options,
+                    **plugin_trust,
+                )
+        else:
+            run_interactive(
+                args.model,
+                workspace,
+                host,
+                allow_shell=args.allow_shell,
+                shell_allowlist=shell_allowlist,
+                shell_timeout=args.shell_timeout,
+                llm_options=llm_options,
+                **plugin_trust,
+            )
+    except LLMError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except (RuntimeError, ValueError) as e:
+        # Resume refusals and eventlog integrity failures land here.
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())