open-agents-ai 0.184.37 → 0.184.39

package/README.md

@@ -505,6 +505,88 @@ OA_API_KEYS="grafana-key:read:grafana,ci-key:run:github-actions,ops-key:admin:op
 curl -H "Authorization: Bearer ops-key" http://localhost:11435/v1/models
 ```
 
+#### Tool-Use Profiles
+
+Enterprise access control — define which tools, shell commands, and settings the agent can use per API key or per request.
+
+**3 built-in presets:**
+
+| Profile | Description | Tools |
+|---------|-------------|-------|
+| `full` | No restrictions | All tools and commands |
+| `ci-safe` | CI/CD — read + test only | file_read, grep, shell (npm test only) |
+| `readonly` | Read-only analysis | No writes, no shell mutations |
+
+```bash
+# List all profiles (presets + custom)
+curl -H "Authorization: Bearer $KEY" http://localhost:11435/v1/profiles
+```
+```json
+{"profiles":[{"name":"readonly","description":"Read-only","encrypted":false,"source":"preset"},{"name":"ci-safe",...}]}
+```
+
+```bash
+# Get profile details
+curl -H "Authorization: Bearer $KEY" http://localhost:11435/v1/profiles/ci-safe
+```
+```json
+{"profile":{"name":"ci-safe","tools":{"allow":["file_read","grep_search","shell"],"shell_allow":["npm test","npx eslint"]},"limits":{"max_turns":15}}}
+```
+
+```bash
+# Create custom profile (admin only)
+curl -X POST http://localhost:11435/v1/profiles \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "frontend-dev",
+    "description": "Frontend team — no backend access",
+    "tools": {
+      "allow": ["file_read", "file_write", "file_edit", "shell", "grep_search"],
+      "shell_deny": ["rm -rf", "sudo", "docker", "kubectl"]
+    },
+    "commands": { "deny": ["destroy", "expose", "sponsor"] },
+    "limits": { "max_turns": 20, "timeout_s": 300 }
+  }'
+```
+
+```bash
+# Create password-protected profile (AES-256-GCM encrypted)
+curl -X POST http://localhost:11435/v1/profiles \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"prod-ops","password":"s3cret","tools":{"deny":["file_write"]}}'
+```
+
+```bash
+# Use a profile with /v1/run (header or body)
+curl -X POST http://localhost:11435/v1/run \
+  -H "Authorization: Bearer $KEY" \
+  -H "X-Tool-Profile: ci-safe" \
+  -H "X-Working-Directory: $(pwd)" \
+  -H "Content-Type: application/json" \
+  -d '{"task":"run the test suite and report failures"}'
+
+# Or in the body:
+curl -X POST http://localhost:11435/v1/run \
+  -H "Authorization: Bearer $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"task":"analyze code quality","profile":"readonly"}'
+```
+
+```bash
+# Load encrypted profile (password in header)
+curl -H "Authorization: Bearer $KEY" \
+  -H "X-Profile-Password: s3cret" \
+  http://localhost:11435/v1/profiles/prod-ops
+```
+
+```bash
+# Delete a custom profile (admin only, presets cannot be deleted)
+curl -X DELETE -H "Authorization: Bearer $ADMIN_KEY" \
+  http://localhost:11435/v1/profiles/frontend-dev
+```
+
 #### Endpoint Reference
 
 | Method | Path | Auth | Description |
@@ -529,6 +611,10 @@ curl -H "Authorization: Bearer ops-key" http://localhost:11435/v1/models
 | PUT | `/v1/config/endpoint` | admin | Switch endpoint |
 | GET | `/v1/commands` | read | List commands |
 | POST | `/v1/commands/:cmd` | run | Execute command |
+| GET | `/v1/profiles` | read | List all profiles (presets + custom) |
+| GET | `/v1/profiles/:name` | read | Get profile details (X-Profile-Password for encrypted) |
+| POST | `/v1/profiles` | admin | Create/update profile (password field for encryption) |
+| DELETE | `/v1/profiles/:name` | admin | Delete custom profile |
 
 ### Enterprise Licensing