Specification, not a feature inventory; current status below. This document defines the target contract architecture for LLM agent integration. Not every capability, method, or enforcement mechanism described here is implemented, and the per-app method tables further down (exact JSON shapes, parameter lists) are illustrative examples rather than a verified API reference; treat them as intent, not as ground truth for what an app currently accepts.

MayteraOS LLM Integration Contracts

Current status (verified 2026-08-06)

The core idea of this document, a risk-classified, temporal, revocable capability token gating what the AI assistant's tool loop can do, is real and substantially built as userland/libc/aicap.h/aicap.c (#293), used by the AI client (aiclient.c). What is verified:

Tools are classified into the same namespaces this page describes (system.*, app.*, fs.*, media.*) with a LOW or HIGH risk level; LOW-risk tools run but are still audit-logged, HIGH-risk tools require a valid token or raise a consent prompt.
Tokens carry real expiry (expires_at), use limits (max_uses), path/command constraints (allowed_paths, denied_commands), and an audit_tag, matching this page's field names closely.
Every authorization decision is appended to /CONFIG/AIAUDIT.LOG; a denied consent fails closed if no consent callback is registered.
26 of the app fleet's manifests declare a real "capabilities" block with actions/queries (24 of those 26 checked had a non-trivial block); the app fleet as a whole is much larger than 26, so most apps currently have no AI capability manifest at all rather than an empty or denying one.

Where this page overstates what exists: tokens are not cryptographically signed JSON objects issued by a named service, as the example in "Capability Token Format" below implies. The real implementation is a plain in-process C struct array inside the calling app; there is no signature field, no issuer, and no separate token-issuing service. Enforcement also currently happens in userland, at the AI client's own dispatch boundary, not inside a protected kernel core; moving it there is tracked as future work (#305) so that a compromised or modified app process cannot bypass the check by skipping its own gate. Read aicap.h directly for the authoritative, current API if you are integrating against this.

Overview

This document defines how LLM agents are intended to interact with MayteraOS applications through the capability-based permission system. All LLM interactions are governed by temporal capability tokens that provide fine-grained access control with mandatory audit trails.

Contract Architecture
Capability Token Format
Application Contracts
IPC Protocol
Security Model
Examples

Contract Architecture

Design Principles

Least Privilege: LLM agents receive only the minimum capabilities needed
Temporal Bounds: All capabilities have explicit expiration times
Audit Trail: Every capability use is logged for accountability
User Consent: Sensitive operations require explicit user approval
Revocability: Capabilities can be revoked at any time

Capability Hierarchy

system.*                    - System-wide capabilities
├── system.settings.*       - Settings access
│   ├── system.settings.read
│   └── system.settings.write
├── system.audio.*          - Audio control
├── system.display.*        - Display settings
└── system.network.*        - Network configuration

app.*                       - Application-specific capabilities
├── app.terminal.*          - Terminal application
│   ├── app.terminal.execute
│   └── app.terminal.read_output
├── app.editor.*            - Text editor
├── app.files.*             - File browser
└── app.syslog.*            - System log viewer

fs.*                        - Filesystem capabilities
├── fs.read                 - Read files
├── fs.write                - Write files
├── fs.delete               - Delete files
└── fs.create               - Create files/directories

media.*                     - Media capabilities
└── media.playback          - Media playback control

Capability Token Format

Token Structure

{
  "token_id": "cap_1234567890abcdef",
  "version": "1.0",
  "issued_at": 1706620800,
  "expires_at": 1706624400,
  "capabilities": [
    "app.terminal.execute",
    "fs.read"
  ],
  "constraints": {
    "max_uses": 10,
    "allowed_paths": ["/home/*"],
    "denied_commands": ["rm -rf", "shutdown"]
  },
  "audit_tag": "Code compilation task",
  "issuer": "maytera.capability.service",
  "signature": "base64_signature_here"
}

Token Fields

Field	Type	Description
`token_id`	string	Unique identifier for the token
`version`	string	Contract version (currently "1.0")
`issued_at`	uint64	Unix timestamp when token was issued
`expires_at`	uint64	Unix timestamp when token expires
`capabilities`	array	List of granted capability strings
`constraints`	object	Additional restrictions on capability use
`max_uses`	int	Maximum number of times token can be used
`audit_tag`	string	Human-readable purpose for logging
`issuer`	string	Service that issued the token
`signature`	string	Cryptographic signature for verification

Application Contracts

Terminal

The Terminal application provides command execution capabilities.

Manifest: /apps/terminal/manifest.json

Capabilities

Capability	Description	Risk Level
`app.terminal.execute`	Execute shell commands	HIGH
`app.terminal.read_output`	Read command output	MEDIUM
`app.terminal.write_input`	Write to command stdin	MEDIUM
`app.terminal.history`	Access command history	LOW

Methods

execute_command

Execute a shell command in the terminal.

{
  "action": "execute",
  "app": "terminal",
  "method": "execute_command",
  "params": {
    "command": "ps",
    "timeout": 30000,
    "capture_output": true
  },
  "capability_token": "cap_..."
}

Parameters:

command (string, required): The command to execute
timeout (int, optional): Timeout in milliseconds (default: 30000)
capture_output (bool, optional): Whether to return stdout/stderr

Returns:

{
  "status": "success",
  "exit_code": 0,
  "stdout": "PID  NAME      STATE\n1    kernel    running\n...",
  "stderr": "",
  "duration_ms": 150
}

Required Capability: app.terminal.execute

get_cwd

Get current working directory.

{
  "action": "query",
  "app": "terminal",
  "method": "get_cwd",
  "capability_token": "cap_..."
}

Returns:

{
  "cwd": "/home/user"
}

Required Capability: app.terminal.read_output

File Browser (Files)

The Files application provides filesystem navigation and management.

Manifest: /apps/files/manifest.json

Capabilities

Capability	Description	Risk Level
`fs.read`	Read file contents	LOW
`fs.write`	Write/modify files	HIGH
`fs.delete`	Delete files	HIGH
`fs.create`	Create files/directories	MEDIUM
`app.files.navigate`	Navigate directories	LOW

Methods

list_directory

List contents of a directory.

{
  "action": "query",
  "app": "files",
  "method": "list_directory",
  "params": {
    "path": "/home/documents"
  },
  "capability_token": "cap_..."
}

Returns:

{
  "path": "/home/documents",
  "entries": [
    {
      "name": "notes.txt",
      "type": "file",
      "size": 1024,
      "modified": 1706620800,
      "permissions": "rw-r--r--"
    },
    {
      "name": "projects",
      "type": "directory",
      "size": 4096,
      "modified": 1706620000,
      "permissions": "rwxr-xr-x"
    }
  ],
  "count": 2
}

Required Capability: fs.read

read_file

Read contents of a file.

{
  "action": "query",
  "app": "files",
  "method": "read_file",
  "params": {
    "path": "/home/documents/notes.txt",
    "offset": 0,
    "length": 4096
  },
  "capability_token": "cap_..."
}

Returns:

{
  "path": "/home/documents/notes.txt",
  "content": "File content here...",
  "size": 1024,
  "encoding": "utf-8"
}

Required Capability: fs.read

write_file

Write content to a file.

{
  "action": "execute",
  "app": "files",
  "method": "write_file",
  "params": {
    "path": "/home/documents/new_file.txt",
    "content": "Hello, World\!",
    "mode": "overwrite"
  },
  "capability_token": "cap_..."
}

Parameters:

path (string, required): File path
content (string, required): Content to write
mode (string, optional): "overwrite" or "append" (default: "overwrite")

Returns:

{
  "status": "success",
  "bytes_written": 13
}

Required Capability: fs.write

delete_file

Delete a file or directory.

{
  "action": "execute",
  "app": "files",
  "method": "delete_file",
  "params": {
    "path": "/home/documents/old_file.txt"
  },
  "capability_token": "cap_..."
}

Required Capability: fs.delete

Settings

The Settings application provides system configuration access.

Manifest: /apps/settings/manifest.json

Capabilities

Capability	Description	Risk Level
`system.settings.read`	Read settings values	LOW
`system.settings.write`	Modify settings	MEDIUM
`system.appearance.read`	Read appearance settings	LOW
`system.appearance.write`	Modify appearance	LOW
`system.audio.read`	Read audio settings	LOW
`system.audio.write`	Modify audio	LOW
`system.network.read`	Read network settings	LOW
`system.network.write`	Modify network	HIGH

Methods

get_setting

Read a setting value.

{
  "action": "query",
  "app": "settings",
  "method": "get_setting",
  "params": {
    "category": "appearance",
    "key": "theme"
  },
  "capability_token": "cap_..."
}

Returns:

{
  "category": "appearance",
  "key": "theme",
  "value": "dark",
  "type": "string"
}

Required Capability: system.settings.read or category-specific read capability

set_setting

Change a setting value.

{
  "action": "execute",
  "app": "settings",
  "method": "set_setting",
  "params": {
    "category": "appearance",
    "key": "theme",
    "value": "light"
  },
  "capability_token": "cap_..."
}

Returns:

{
  "status": "success",
  "previous_value": "dark",
  "new_value": "light"
}

Required Capability: system.settings.write or category-specific write capability

Setting Categories

Appearance

theme (string): "dark", "light", "classic", "ocean"
accent_color (string): "blue", "green", "orange", "purple", "red"
font_size (string): "small", "medium", "large"
animations_enabled (bool)
transparency_enabled (bool)

Display

brightness (int): 0-100
resolution (string): "1920x1080", "1280x720", etc.
refresh_rate (int): 60, 75, 120, etc.
night_light (bool)

Sound

master_volume (int): 0-100
input_volume (int): 0-100
output_device (string)
input_device (string)
sound_effects (bool)

Network

dhcp_enabled (bool)
wifi_enabled (bool)
ip_address (string)
gateway (string)
dns_servers (array)

Keyboard

layout (string): "us", "uk", "de", "fr"
repeat_rate (string): "slow", "normal", "fast"
repeat_delay (string): "short", "normal", "long"

DateTime

timezone (string)
use_24hour (bool)
auto_time (bool)

Editor

The Editor application provides text editing capabilities.

Manifest: /apps/editor/manifest.json

Capabilities

Capability	Description	Risk Level
`app.editor.read`	Read editor buffer	LOW
`app.editor.write`	Modify editor buffer	MEDIUM
`app.editor.file_open`	Open files in editor	MEDIUM
`app.editor.file_save`	Save files from editor	MEDIUM

Methods

open_file

Open a file in the editor.

{
  "action": "execute",
  "app": "editor",
  "method": "open_file",
  "params": {
    "path": "/home/documents/code.c"
  },
  "capability_token": "cap_..."
}

Required Capability: app.editor.file_open

get_buffer

Get current editor buffer contents.

{
  "action": "query",
  "app": "editor",
  "method": "get_buffer",
  "capability_token": "cap_..."
}

Returns:

{
  "content": "int main() {\n    return 0;\n}",
  "filename": "code.c",
  "modified": true,
  "line_count": 3,
  "cursor_line": 2,
  "cursor_col": 4
}

Required Capability: app.editor.read

set_buffer

Replace editor buffer contents.

{
  "action": "execute",
  "app": "editor",
  "method": "set_buffer",
  "params": {
    "content": "// Modified content\nint main() { return 0; }"
  },
  "capability_token": "cap_..."
}

Required Capability: app.editor.write

save_file

Save current buffer to file.

{
  "action": "execute",
  "app": "editor",
  "method": "save_file",
  "params": {
    "path": "/home/documents/code.c"
  },
  "capability_token": "cap_..."
}

Required Capability: app.editor.file_save

Calculator

The Calculator application provides mathematical operations.

Manifest: /apps/calc/manifest.json

Capabilities

Capability	Description	Risk Level
`app.calc.compute`	Perform calculations	LOW
`app.calc.read`	Read current value	LOW

Methods

compute

Perform a calculation.

{
  "action": "execute",
  "app": "calc",
  "method": "compute",
  "params": {
    "expression": "123 + 456 * 2"
  },
  "capability_token": "cap_..."
}

Returns:

{
  "result": 1035,
  "expression": "123 + 456 * 2"
}

Required Capability: app.calc.compute

get_value

Get current calculator display value.

{
  "action": "query",
  "app": "calc",
  "method": "get_value",
  "capability_token": "cap_..."
}

Returns:

{
  "value": 1035,
  "display": "1035"
}

Required Capability: app.calc.read

System Log (Syslog)

The Syslog application provides access to system logs.

Manifest: /apps/syslog/manifest.json

Capabilities

Capability	Description	Risk Level
`app.syslog.read`	Read log entries	LOW
`app.syslog.filter`	Filter log entries	LOW

Methods

get_logs

Retrieve log entries.

{
  "action": "query",
  "app": "syslog",
  "method": "get_logs",
  "params": {
    "count": 100,
    "offset": 0,
    "severity": "all"
  },
  "capability_token": "cap_..."
}

Parameters:

count (int, optional): Number of entries (default: 100)
offset (int, optional): Start offset (default: 0)
severity (string, optional): "all", "info", "warn", "error", "ok"

Returns:

{
  "entries": [
    {
      "timestamp": 1706620800,
      "severity": "info",
      "message": "[INFO] MayteraOS System Log Viewer"
    },
    {
      "timestamp": 1706620801,
      "severity": "ok",
      "message": "[OK] Kernel initialized successfully"
    }
  ],
  "total": 150,
  "returned": 100
}

Required Capability: app.syslog.read

Solitaire

The Solitaire game application.

Manifest: /apps/solitaire/manifest.json

Capabilities

Capability	Description	Risk Level
`app.solitaire.play`	Interact with game	LOW
`app.solitaire.read`	Read game state	LOW

Methods

get_game_state

Get current game state.

{
  "action": "query",
  "app": "solitaire",
  "method": "get_game_state",
  "capability_token": "cap_..."
}

Returns:

{
  "in_progress": true,
  "moves": 42,
  "time_elapsed": 180,
  "cards_remaining": 24
}

Required Capability: app.solitaire.read

new_game

Start a new game.

{
  "action": "execute",
  "app": "solitaire",
  "method": "new_game",
  "capability_token": "cap_..."
}

Required Capability: app.solitaire.play

Python Interpreter

The Python (MicroPython) application provides scripting capabilities.

Manifest: /apps/python/manifest.json

Capabilities

Capability	Description	Risk Level
`app.python.execute`	Execute Python code	HIGH
`app.python.read_output`	Read execution output	MEDIUM

Methods

execute_script

Execute Python code.

{
  "action": "execute",
  "app": "python",
  "method": "execute_script",
  "params": {
    "code": "print(Hello from Python!)\nresult = 2 + 2\nprint(fResult: {result})",
    "timeout": 5000
  },
  "capability_token": "cap_..."
}

Returns:

{
  "status": "success",
  "output": "Hello from Python\!\nResult: 4\n",
  "error": null,
  "duration_ms": 50
}

Required Capability: app.python.execute

execute_file

Execute a Python script file.

{
  "action": "execute",
  "app": "python",
  "method": "execute_file",
  "params": {
    "path": "/home/scripts/hello.py"
  },
  "capability_token": "cap_..."
}

Required Capabilities: app.python.execute, fs.read

IPC Protocol

Message Format

All LLM-to-application communication uses the MayteraOS IPC system.

{
  "header": {
    "msg_type": "llm_request",
    "version": "1.0",
    "request_id": "req_abc123",
    "timestamp": 1706620800
  },
  "body": {
    "action": "execute",
    "app": "terminal",
    "method": "execute_command",
    "params": {...},
    "capability_token": "cap_..."
  }
}

Response Format

{
  "header": {
    "msg_type": "llm_response",
    "version": "1.0",
    "request_id": "req_abc123",
    "timestamp": 1706620801
  },
  "body": {
    "status": "success",
    "result": {...}
  }
}

Error Response

{
  "header": {
    "msg_type": "llm_response",
    "version": "1.0",
    "request_id": "req_abc123",
    "timestamp": 1706620801
  },
  "body": {
    "status": "error",
    "error_code": "CAPABILITY_DENIED",
    "error_message": "Capability fs.write not granted in token",
    "details": {
      "required_capability": "fs.write",
      "token_capabilities": ["fs.read"]
    }
  }
}

Error Codes

Code	Description
`CAPABILITY_DENIED`	Token lacks required capability
`TOKEN_EXPIRED`	Capability token has expired
`TOKEN_EXHAUSTED`	Token max_uses exceeded
`INVALID_TOKEN`	Token signature verification failed
`INVALID_REQUEST`	Malformed request
`APP_NOT_FOUND`	Target application not running
`METHOD_NOT_FOUND`	Unknown method name
`EXECUTION_FAILED`	Method execution error
`TIMEOUT`	Operation timed out

Security Model

Capability Request Flow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   LLM Agent     │    │ Capability Svc  │    │      User       │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │
         │ 1. Request capability│                      │
         │─────────────────────>│                      │
         │                      │ 2. Prompt for consent│
         │                      │─────────────────────>│
         │                      │                      │
         │                      │ 3. User approves     │
         │                      │<─────────────────────│
         │                      │                      │
         │ 4. Issue token       │                      │
         │<─────────────────────│                      │
         │                      │                      │

Sensitive Operations

The following operations always require user consent:

File deletion (fs.delete)
Command execution (app.terminal.execute)
Python code execution (app.python.execute)
Network configuration (system.network.write)
System settings changes (system.settings.write)

Audit Logging

All capability uses are logged:

{
  "timestamp": 1706620800,
  "token_id": "cap_1234567890abcdef",
  "action": "execute",
  "app": "terminal",
  "method": "execute_command",
  "params_hash": "sha256:...",
  "result": "success",
  "audit_tag": "Code compilation task"
}

Examples

Example 1: Requesting Capability

LLM requests capability to execute terminal commands:

{
  "action": "request_capability",
  "capabilities": ["app.terminal.execute"],
  "duration": 3600,
  "max_uses": 10,
  "reason": "Inspect running processes for the user",
  "constraints": {
    "allowed_commands": ["ps", "help"],
    "denied_patterns": ["rm -rf", "sudo"]
  }
}

Example 2: Executing Command

After obtaining capability token:

{
  "action": "execute",
  "app": "terminal",
  "method": "execute_command",
  "params": {
    "command": "ps",
    "timeout": 60000
  },
  "capability_token": "cap_1234567890abcdef"
}

Example 3: Reading and Modifying Settings

{
  "action": "query",
  "app": "settings",
  "method": "get_setting",
  "params": {
    "category": "appearance",
    "key": "theme"
  },
  "capability_token": "cap_..."
}

{
  "action": "execute",
  "app": "settings",
  "method": "set_setting",
  "params": {
    "category": "appearance",
    "key": "theme",
    "value": "dark"
  },
  "capability_token": "cap_..."
}

Example 4: File Operations

{
  "action": "query",
  "app": "files",
  "method": "list_directory",
  "params": {
    "path": "/home/user/projects"
  },
  "capability_token": "cap_..."
}

{
  "action": "query",
  "app": "files",
  "method": "read_file",
  "params": {
    "path": "/home/user/projects/config.json"
  },
  "capability_token": "cap_..."
}

Version History

Version	Date	Changes
1.0	2026-01-30	Initial release

MayteraOS LLM integration contracts, specification version 1.0.

MayteraOS LLM Integration Contracts

Current status (verified 2026-08-06)

Overview

Table of Contents

Contract Architecture

Design Principles

Capability Hierarchy

Capability Token Format

Token Structure

Token Fields

Application Contracts

Terminal

Capabilities

Methods

execute_command

get_cwd

File Browser (Files)

Capabilities

Methods

list_directory

read_file

write_file

delete_file

Settings

Capabilities

Methods

get_setting

set_setting

Setting Categories

Appearance

Display

Sound

Network

Keyboard

DateTime

Editor

Capabilities

Methods

open_file

get_buffer

set_buffer

save_file

Calculator

Capabilities

Methods

compute

get_value

System Log (Syslog)

Capabilities

Methods

get_logs

Solitaire

Capabilities

Methods

get_game_state

new_game

Python Interpreter

Capabilities

Methods

execute_script

execute_file

IPC Protocol

Message Format

Response Format

Error Response

Error Codes

Security Model

Capability Request Flow

Sensitive Operations

Audit Logging

Examples

Example 1: Requesting Capability

Example 2: Executing Command

Example 3: Reading and Modifying Settings

Example 4: File Operations

Version History