omnius 1.0.342 → 1.0.343

package/README.md

@@ -225,13 +225,53 @@ The complete endpoint inventory follows. It is kept in lockstep with the served
 | `GET` | `/v1/skills` · `/v1/skills/{name}` | List · load skill content |
 | `GET` | `/v1/commands` | List slash commands |
 | `POST` | `/v1/commands/{cmd}` | Execute slash command |
-| `GET` | `/v1/tools` · `/v1/tools/{name}` | List · tool metadata |
+| `GET` | `/v1/tools` · `/v1/tools/{name}` | List (built-in + external) · tool metadata |
+| `POST` | `/v1/tools/register` | Register an application-specific external tool |
+| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |
 | `POST` | `/v1/tools/{name}/call` | Call tool |
+| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |
 | `GET` | `/v1/mcps` · `/v1/mcps/{name}` | List · MCP server details |
 | `POST` | `/v1/mcps/{name}/call` | Call MCP tool |
 | `GET` | `/v1/hooks` · `/v1/agents` | Hook registry · agent type registry |
 | `GET` | `/v1/codegraph/snapshot` · `/v1/codegraph/events` | Code graph snapshot · SSE |
 
+### Registering application-specific tools
+
+Agents integrating Omnius into their own stack can register tools at runtime so the Omnius agent loop can call them alongside built-ins. Registration is a single unified contract — `transport.type` selects how Omnius reaches the implementation:
+
+- **`http`** — Omnius POSTs `{name, args, session_id}` to a `callback_url` your app hosts and relays the response.
+- **`mcp`** — the tool proxies to a named tool on an MCP server (auto-connected when you pass `connect`).
+
+Registered tools are persisted per working directory (`.omnius/external-tools.json`), surface in `GET /v1/tools`, and respect the same scope/off-device security gate as built-ins. Registration needs `run` scope (remote callers need `admin`).
+
+```bash
+# Register an HTTP-backed tool
+curl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{
+  "name": "lookup_order",
+  "description": "Look up an order by id in the billing system",
+  "parameters": {"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},
+  "security": {"requires_scope":"run","risk":"low"},
+  "transport": {"type":"http","callback_url":"https://app.internal/tools/lookup_order","auth_header":"Bearer …"}
+}'
+
+# It now appears in the registry and is directly callable
+curl -s localhost:11435/v1/tools/lookup_order
+curl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{"args":{"id":"A-1001"}}'
+
+# Evaluate it against cases during development (pass/fail + metrics)
+curl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{
+  "cases": [
+    {"name":"known order","args":{"id":"A-1001"},"expect":{"success":true,"output_contains":"A-1001"}},
+    {"name":"missing order","args":{"id":"nope"},"expect":{"success":false}}
+  ]
+}'
+
+# Unregister when done
+curl -s -X DELETE localhost:11435/v1/tools/lookup_order
+```
+
+The same registration accepts an MCP transport, e.g. `"transport":{"type":"mcp","server":"acme","tool":"search","connect":{"url":"https://app.internal/mcp","transport":"streamable-http"}}`.
+
 ### AIWG
 
 | Method | Path | Purpose |