CLI Executor Extension for AgentOS

Execute shell commands, run scripts, and manage files for AgentOS agents. This is one of the two fundamental primitives (along with Web Browser) that enables recursive self-building agent capabilities.

Features

• Shell Execution: Run any shell command with output capture
• File Management: Read, write, and list files/directories
• Security Controls: Dangerous command detection and blocking
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

npm install @framers/agentos-ext-cli-executor

Quick Start

import { createExtensionPack } from '@framers/agentos-ext-cli-executor';
import { ExtensionManager } from '@framers/agentos';

const extensionManager = new ExtensionManager();

// Register the CLI extension
extensionManager.register(createExtensionPack({
  options: {
    defaultShell: 'bash',
    timeout: 60000,
    blockedCommands: ['rm -rf /', 'format']
  },
  logger: console
}));

Tools

shellExecute

Execute a shell command.

const result = await gmi.executeTool('shellExecute', {
  command: 'npm install lodash',
  cwd: '/path/to/project',
  timeout: 30000
});
// Returns: { command, exitCode, stdout, stderr, duration, success }

fileRead

Read file contents.

const result = await gmi.executeTool('fileRead', {
  path: './package.json',
  encoding: 'utf-8'
});
// Returns: { path, content, size, truncated, encoding }

// Read last 50 lines
const logs = await gmi.executeTool('fileRead', {
  path: './app.log',
  lines: 50,
  fromEnd: true
});

fileWrite

Write content to a file.

const result = await gmi.executeTool('fileWrite', {
  path: './config.json',
  content: JSON.stringify({ key: 'value' }),
  createDirs: true
});
// Returns: { path, bytesWritten, created, appended }

listDirectory

List directory contents.

const result = await gmi.executeTool('listDirectory', {
  path: './src',
  recursive: true,
  pattern: '*.ts',
  includeStats: true
});
// Returns: { path, entries: [{ name, path, type, size, ... }], count }

Security

The extension includes built-in security controls:

Dangerous Pattern Detection

Commands matching these patterns are blocked by default:

• rm -rf / (recursive delete root)
• format C: (format drives)
• Fork bombs
• Direct disk writes
• System shutdown/reboot commands

Custom Blocklists

createExtensionPack({
  options: {
    blockedCommands: ['sudo', 'su', 'chmod 777'],
    allowedCommands: ['npm', 'node', 'python', 'git'] // Whitelist mode
  }
});

Risk Assessment

Each command is assessed for risk level:

| Risk Level | Examples | |------------|----------| | safe | ls, cat, npm list | | low | echo "text" > file.txt | | medium | rm file.txt, eval | | high | sudo, curl | sh | | critical | rm -rf /, blocked patterns |

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | defaultShell | string | auto | Shell to use (bash, powershell, cmd, zsh) | | timeout | number | 60000 | Default timeout (ms) | | workingDirectory | string | process.cwd() | Default working directory | | allowedCommands | string[] | [] | Command whitelist (empty = all) | | blockedCommands | string[] | [...] | Command blacklist | | env | object | {} | Environment variables |

Use Cases

Code Generation and Execution

// Write generated code
await gmi.executeTool('fileWrite', {
  path: './generated/app.py',
  content: generatedPythonCode,
  createDirs: true
});

// Execute it
await gmi.executeTool('shellExecute', {
  command: 'python ./generated/app.py',
  timeout: 30000
});

Project Setup

// Create project structure
await gmi.executeTool('shellExecute', {
  command: 'npx create-react-app my-app --template typescript'
});

// Install dependencies
await gmi.executeTool('shellExecute', {
  command: 'npm install axios lodash',
  cwd: './my-app'
});

Log Analysis

// Read recent logs
const logs = await gmi.executeTool('fileRead', {
  path: '/var/log/app.log',
  lines: 100,
  fromEnd: true
});

// Parse and analyze
const errorCount = logs.output.content.match(/ERROR/g)?.length || 0;

The Two Primitives Theory

This extension, combined with the Web Browser extension, provides the two fundamental capabilities needed for a recursive self-building agent:

1. CLI Executor (this extension)

   • Execute arbitrary code
   • Manage files
   • Install dependencies
   • Run tests and builds

2. Web Browser (see web-browser extension)

   • Search for information
   • Read documentation
   • Learn new techniques
   • Verify implementations

Together, an intelligent agent can:

1. Identify what it needs to learn → Web search
2. Find documentation/tutorials → Web scraping
3. Write code → File write
4. Execute and test → Shell execute
5. Debug and iterate → Repeat

License

MIT © Frame.dev