OPAL Design

OPAL (Operator Permission and Access Layer) is the machine-manageable control layer that enables LLMs to interact with agent resources safely.

Did You Know?

OPAL's permission system is inspired by Android's app permissions, but with richer temporal controls. You can grant an LLM "one-time" access (just this operation), "session" access (until the app closes), or "persistent" access (until explicitly revoked). This gives you fine-grained control over how much autonomy your AI assistant has.

What OPAL provides

Command API

LLMs interact via structured JSON commands rather than free-form text.

Discovery

LLMs can enumerate available commands:

{"command": "enumerate_commands"}

Response:
{
  "commands": [
    "create_plan",
    "list_plans",
    "add_guest",
    "set_target",
    "query_sensors",
    ...
  ]
}

Execution

Commands are issued as JSON objects:

{"command": "create_plan", "title": "Patrol Route A"}

Response:
{
  "result": "success",
  "plan_id": "abc123"
}

Permission denied

When permissions are missing:

{"command": "create_plan", "title": "Patrol Route A"}

Response:
{
  "result": "failed",
  "reason": "Missing permission: plan.create",
  "hint": "Use ask_permission to request access"
}

Self-documentation

Each endpoint describes itself:

{"command": "describe", "target": "create_plan"}

Response:
{
  "description": "Creates a new behavior plan",
  "parameters": {
    "title": "string (required)",
    "template": "string (optional)"
  },
  "permissions": ["plan.create"],
  "examples": [
    {"command": "create_plan", "title": "My Plan"}
  ]
}

Permission model

Inspired by Android's permission system but with richer context.

Permission types

Permission prompts

When an LLM requests a new permission:

Temporal scopes

Permission features

• Granular - Fine-grained per-resource permissions
• Temporal - One-time, session, or persistent
• Revocable - Dashboard to review and revoke grants
• Auditable - All grants and uses logged

User consent model

Principles

1. LLM must request permission before sensitive operations
2. User sees human-readable description of intended action
3. Clear indication of scope and affected resources
4. No silent operations on protected resources

Consent flow

Audit logging

All OPAL interactions are logged:

{
  "timestamp": "2025-01-15T14:32:01Z",
  "command": "set_target",
  "parameters": {"location": "kitchen"},
  "permission_checked": "navigation.set_target",
  "permission_status": "granted",
  "result": "success",
  "resources_affected": ["agent.navigation"]
}

Log contents

Log access

• Viewable in admin interface
• Exportable for analysis
• Used for debugging and security review

Error handling

Graceful failures

• Clear error messages with actionable hints
• No cascading failures - each command is atomic
• LLM can retry or request missing permissions

Example error responses

Invalid command:

{
  "result": "error",
  "error": "unknown_command",
  "message": "Command 'foobar' not recognized",
  "hint": "Use enumerate_commands to see available commands"
}

Invalid parameters:

{
  "result": "error",
  "error": "invalid_parameters",
  "message": "Parameter 'speed' must be between 0 and 100",
  "received": 150
}

Resource not found:

{
  "result": "error",
  "error": "not_found",
  "message": "Node 'Charlie' not found in address book"
}

Hallucination containment

LLMs can generate plausible but incorrect outputs. OPAL contains this:

• Invalid commands rejected with schema errors
• Unknown resources return clear "not found" errors
• Permission system prevents unauthorized actions regardless of LLM confidence
• Structured JSON prevents injection attacks

Permission categories

Plan permissions

Navigation permissions

Sensor permissions

Node permissions