mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-08-05 17:08:33 +00:00
148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
# Extension Authoring
|
|
|
|
A native nanobot extension is a directory containing:
|
|
|
|
```text
|
|
nanobot-review/
|
|
├── nanobot.extension.json
|
|
└── extension.py
|
|
```
|
|
|
|
The manifest describes identity, activation prerequisites, and requested
|
|
permissions. The Python entry point performs the real registration. This keeps
|
|
one authoritative source for tool, command, and hook ownership.
|
|
|
|
## Manifest
|
|
|
|
```json
|
|
{
|
|
"id": "acme.review",
|
|
"name": "Acme Review",
|
|
"version": "1.0.0",
|
|
"entry": "extension:register",
|
|
"description": "Adds repository review tools.",
|
|
"apiVersion": 1,
|
|
"license": "MIT",
|
|
"homepage": "https://github.com/acme/nanobot-review",
|
|
"dependencies": [
|
|
{
|
|
"kind": "executable",
|
|
"name": "git"
|
|
}
|
|
],
|
|
"permissions": [
|
|
{
|
|
"name": "workspace.read",
|
|
"reason": "Read files selected for review."
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Required fields are `id`, `name`, and `version`. `entry` defaults to
|
|
`"extension:register"` and `apiVersion` defaults to `1`.
|
|
|
|
IDs use lowercase letters, digits, dots, underscores, and hyphens. Entry points
|
|
use `module:function` syntax and must resolve inside the package.
|
|
|
|
### Dependencies
|
|
|
|
| Kind | Meaning |
|
|
|---|---|
|
|
| `python` | Installed Python distribution; `specifier` accepts a version constraint |
|
|
| `executable` | Command available on `PATH` |
|
|
| `environment` | Non-empty environment variable |
|
|
|
|
Set `"optional": true` when a missing dependency should not block activation.
|
|
|
|
### Permissions
|
|
|
|
Permissions are lowercase namespaced identifiers chosen by the package, such
|
|
as `workspace.read` or `network`. Give each permission a concrete reason.
|
|
Activation waits until every requested permission is granted.
|
|
|
|
The host currently uses permissions as explicit user consent. They do not
|
|
sandbox Python code, so do not describe a permission as stronger isolation
|
|
than it provides.
|
|
|
|
## Registration API
|
|
|
|
The entry point receives `PythonExtensionApi` and must return `None`:
|
|
|
|
```python
|
|
from typing import Any
|
|
|
|
from nanobot.agent.tools.base import Tool
|
|
|
|
|
|
class ReviewTool(Tool):
|
|
@property
|
|
def name(self) -> str:
|
|
return "review_repository"
|
|
|
|
@property
|
|
def description(self) -> str:
|
|
return "Review the current repository."
|
|
|
|
@property
|
|
def parameters(self) -> dict[str, Any]:
|
|
return {"type": "object", "properties": {}}
|
|
|
|
async def execute(self, **kwargs: Any) -> str:
|
|
return "No findings."
|
|
|
|
|
|
def register(api) -> None:
|
|
api.register_tool(ReviewTool())
|
|
```
|
|
|
|
The API has three stable methods:
|
|
|
|
```python
|
|
api.register_tool(tool)
|
|
api.register_command("review", handler)
|
|
api.register_hook_factory(factory)
|
|
```
|
|
|
|
Command handlers use nanobot's `CommandContext` and return an
|
|
`OutboundMessage` or `None`. Hook factories receive `AgentTurnHookContext` and
|
|
return an `AgentHook` or `None`.
|
|
|
|
Do not modify `AgentLoop` or global registries directly. The API tags every
|
|
registration with the extension ID so reload, failure rollback, and uninstall
|
|
can remove exactly what the package owns.
|
|
|
|
## Collision and failure behavior
|
|
|
|
Tool and command names are unique across core and active extensions. If an
|
|
extension registers a duplicate name, activation fails for that extension and
|
|
all of its partial registrations are rolled back.
|
|
|
|
Missing dependencies are reported as diagnostics instead of crashing the
|
|
gateway.
|
|
|
|
## Develop locally
|
|
|
|
1. Create the manifest and entry module.
|
|
2. Install the directory with `--kind local`.
|
|
3. Inspect and grant its permissions.
|
|
4. Trust it.
|
|
5. Reinstall after editing so nanobot records a new integrity digest.
|
|
|
|
```bash
|
|
nanobot extensions install "$PWD" --kind local
|
|
nanobot extensions inspect acme.review
|
|
nanobot extensions permissions acme.review workspace.read
|
|
nanobot extensions trust acme.review
|
|
```
|
|
|
|
Keep tests in the extension repository. At minimum, test registration,
|
|
duplicate-name failure, and behavior when each required dependency is missing.
|
|
|
|
## Distribution
|
|
|
|
Publish the directory in a Git repository. Users can pin a release tag or
|
|
commit with `--ref`. The repository root must contain
|
|
`nanobot.extension.json`; install scripts and generated compatibility manifests
|
|
are not part of the native contract.
|