@framers/agentos-ext-cli-executor 1.1.0

package/README.md

@@ -0,0 +1,221 @@
+# 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
+
+```bash
+npm install @framers/agentos-ext-cli-executor
+```
+
+## Quick Start
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+
+

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * AgentOS CLI Executor Extension
+ *
+ * Provides shell command execution, script running, and file management
+ * capabilities for AgentOS agents.
+ *
+ * @module @framers/agentos-ext-cli-executor
+ * @version 1.0.0
+ * @license MIT
+ */
+import type { ExtensionContext, ExtensionPack } from '@framers/agentos';
+import type { ShellConfig } from './types';
+/**
+ * Extension configuration options
+ */
+export interface CLIExecutorExtensionOptions extends ShellConfig {
+    /** Extension priority in the stack */
+    priority?: number;
+}
+/**
+ * Creates the CLI executor extension pack
+ *
+ * @param context - The extension context
+ * @returns The configured extension pack
+ *
+ * @example
+ * ```typescript
+ * import { createExtensionPack } from '@framers/agentos-ext-cli-executor';
+ *
+ * const pack = createExtensionPack({
+ *   options: {
+ *     defaultShell: 'bash',
+ *     timeout: 60000,
+ *     blockedCommands: ['rm -rf /']
+ *   },
+ *   logger: console
+ * });
+ * ```
+ */
+export declare function createExtensionPack(context: ExtensionContext): ExtensionPack;
+export { ShellService } from './services/shellService';
+export { ExecuteTool } from './tools/execute';
+export { FileReadTool } from './tools/fileRead';
+export { FileWriteTool } from './tools/fileWrite';
+export { ListDirectoryTool } from './tools/listDir';
+export * from './types';
+export default createExtensionPack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,WAAW;IAC9D,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAqE5E;AAGD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,cAAc,SAAS,CAAC;AAGxB,eAAe,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,110 @@
+/**
+ * AgentOS CLI Executor Extension
+ *
+ * Provides shell command execution, script running, and file management
+ * capabilities for AgentOS agents.
+ *
+ * @module @framers/agentos-ext-cli-executor
+ * @version 1.0.0
+ * @license MIT
+ */
+import { ShellService } from './services/shellService';
+import { ExecuteTool } from './tools/execute';
+import { FileReadTool } from './tools/fileRead';
+import { FileWriteTool } from './tools/fileWrite';
+import { ListDirectoryTool } from './tools/listDir';
+/**
+ * Creates the CLI executor extension pack
+ *
+ * @param context - The extension context
+ * @returns The configured extension pack
+ *
+ * @example
+ * ```typescript
+ * import { createExtensionPack } from '@framers/agentos-ext-cli-executor';
+ *
+ * const pack = createExtensionPack({
+ *   options: {
+ *     defaultShell: 'bash',
+ *     timeout: 60000,
+ *     blockedCommands: ['rm -rf /']
+ *   },
+ *   logger: console
+ * });
+ * ```
+ */
+export function createExtensionPack(context) {
+    const options = context.options || {};
+    // Initialize shell service with configuration
+    const shellService = new ShellService({
+        defaultShell: options.defaultShell,
+        timeout: options.timeout,
+        workingDirectory: options.workingDirectory,
+        allowedCommands: options.allowedCommands,
+        blockedCommands: options.blockedCommands,
+        env: options.env,
+    });
+    // Create tool instances
+    const executeTool = new ExecuteTool(shellService);
+    const fileReadTool = new FileReadTool(shellService);
+    const fileWriteTool = new FileWriteTool(shellService);
+    const listDirectoryTool = new ListDirectoryTool(shellService);
+    return {
+        name: '@framers/agentos-ext-cli-executor',
+        version: '1.0.0',
+        descriptors: [
+            {
+                id: 'shellExecute',
+                kind: 'tool',
+                priority: options.priority || 50,
+                payload: executeTool,
+            },
+            {
+                id: 'fileRead',
+                kind: 'tool',
+                priority: options.priority || 50,
+                payload: fileReadTool,
+            },
+            {
+                id: 'fileWrite',
+                kind: 'tool',
+                priority: options.priority || 50,
+                payload: fileWriteTool,
+            },
+            {
+                id: 'listDirectory',
+                kind: 'tool',
+                priority: options.priority || 50,
+                payload: listDirectoryTool,
+            },
+        ],
+        /**
+         * Called when extension is activated
+         */
+        onActivate: async () => {
+            if (context.onActivate) {
+                await context.onActivate();
+            }
+            context.logger?.info('CLI Executor Extension activated');
+        },
+        /**
+         * Called when extension is deactivated
+         */
+        onDeactivate: async () => {
+            if (context.onDeactivate) {
+                await context.onDeactivate();
+            }
+            context.logger?.info('CLI Executor Extension deactivated');
+        },
+    };
+}
+// Export types and classes for consumers
+export { ShellService } from './services/shellService';
+export { ExecuteTool } from './tools/execute';
+export { FileReadTool } from './tools/fileRead';
+export { FileWriteTool } from './tools/fileWrite';
+export { ListDirectoryTool } from './tools/listDir';
+export * from './types';
+// Default export for convenience
+export default createExtensionPack;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/services/shellService.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shell Service
+ * Manages command execution with security validation.
+ *
+ * @module @framers/agentos-ext-cli-executor
+ */
+import type { ShellConfig, ExecutionResult, ScriptOptions, ScriptResult, FileReadOptions, FileReadResult, FileWriteOptions, FileWriteResult, ListDirectoryOptions, ListDirectoryResult, SecurityCheckResult } from '../types';
+/**
+ * Shell service for executing commands
+ */
+export declare class ShellService {
+    private config;
+    constructor(config?: ShellConfig);
+    /**
+     * Detect the appropriate shell for the current platform
+     */
+    private detectShell;
+    /**
+     * Check if a command is safe to execute
+     */
+    checkSecurity(command: string): SecurityCheckResult;
+    /**
+     * Execute a shell command
+     */
+    execute(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeout?: number;
+    }): Promise<ExecutionResult>;
+    /**
+     * Run a script file
+     */
+    runScript(scriptPath: string, options?: ScriptOptions): Promise<ScriptResult>;
+    /**
+     * Read a file
+     */
+    readFile(filePath: string, options?: FileReadOptions): Promise<FileReadResult>;
+    /**
+     * Write to a file
+     */
+    writeFile(filePath: string, content: string, options?: FileWriteOptions): Promise<FileWriteResult>;
+    /**
+     * List directory contents
+     */
+    listDirectory(dirPath: string, options?: ListDirectoryOptions): Promise<ListDirectoryResult>;
+}
+//# sourceMappingURL=shellService.d.ts.map

package/dist/services/shellService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellService.d.ts","sourceRoot":"","sources":["../../src/services/shellService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EAEnB,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAuBlB;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAc;gBAEhB,MAAM,GAAE,WAAgB;IASpC;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB;IAuEnD;;OAEG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACzE,OAAO,CAAC,eAAe,CAAC;IAwD3B;;OAEG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC;IAiCxB;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IA4CpF;;OAEG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAkC3B;;OAEG;IACG,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;CA6EhC"}