Skip to content

Self-improving AI Employees for everyone

feat: add 4 filesystem/shell dual-purpose tool nodes

trohitg49e0d3e00494
diff --git a/.env.template b/.env.template
index a4c9f5b1..3814165f 100644
--- a/.env.template
+++ b/.env.template
@@ -46,6 +46,9 @@ TEMPORAL_SERVER_ADDRESS=localhost:7233
TEMPORAL_NAMESPACE=default
TEMPORAL_TASK_QUEUE=machina-tasks
+# Deep Agent workspace (root directory for filesystem/shell tools)
+DEEP_AGENT_WORKSPACE=./workspace
+
# Logging
LOG_LEVEL=INFO
LOG_FORMAT=text
diff --git a/CLAUDE.md b/CLAUDE.md
index cceb56ac..ccbd958c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -401,7 +401,7 @@ class CacheEntry(SQLModel, table=True):
## Codebase Summary
- **Hybrid architecture**: Node.js + Python + React TypeScript
-- **97 implemented workflow nodes** with clean service separation (9 AI models + 3 AI agents/memory + 16 specialized agents + 1 skill + 4 dedicated tools + 3 search + 16 Android + 3 WhatsApp + 4 Twitter + 2 Telegram + 2 Social + 3 Location + 3 Code + 6 Utility + 6 Document + 2 Chat + 2 Scheduler + 2 Workflow + 7 Google Workspace + 1 Apify + 1 Crawlee + 3 Proxy)
+- **101 implemented workflow nodes** with clean service separation (9 AI models + 3 AI agents/memory + 16 specialized agents + 1 skill + 4 dedicated tools + 3 search + 16 Android + 3 WhatsApp + 4 Twitter + 2 Telegram + 2 Social + 3 Location + 3 Code + 6 Utility + 6 Document + 2 Chat + 2 Scheduler + 2 Workflow + 7 Google Workspace + 1 Apify + 1 Crawlee + 3 Proxy + 4 Filesystem/Shell)
- **WebSocket-First Architecture**: WebSocket as primary frontend-backend communication (89 message handlers)
- **Recent optimizations**: REST APIs replaced with WebSocket, AI endpoints migrated to Python, Android automation integrated
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsx
index e938168d..ea30c924 100644
--- a/client/src/Dashboard.tsx
+++ b/client/src/Dashboard.tsx
@@ -37,6 +37,7 @@ import { APIFY_NODE_TYPES } from './nodeDefinitions/apifyNodes';
import { GOOGLE_WORKSPACE_NODE_TYPES } from './nodeDefinitions/googleWorkspaceNodes';
import { PROXY_NODE_TYPES } from './nodeDefinitions/proxyNodes';
import { CRAWLEE_NODE_TYPES } from './nodeDefinitions/crawleeNodes';
+import { FILESYSTEM_NODE_TYPES } from './nodeDefinitions/filesystemNodes';
import { AI_CHAT_MODEL_TYPES } from './nodeDefinitions/aiModelNodes';
import ParameterPanel from './ParameterPanel';
import LocationParameterPanel from './components/LocationParameterPanel';
@@ -149,6 +150,9 @@ const createNodeTypes = (): Record<string, React.ComponentType<any>> => {
} else if (CRAWLEE_NODE_TYPES.includes(type)) {
// Crawlee web scraping nodes use SquareNode component
types[type] = SquareNode;
+ } else if (FILESYSTEM_NODE_TYPES.includes(type)) {
+ // Filesystem & shell nodes use SquareNode component
+ types[type] = SquareNode;
} else if (SOCIAL_NODE_TYPES.includes(type)) {
// Social nodes use AIAgentNode for multiple output handles support
types[type] = AIAgentNode;
diff --git a/client/src/components/parameterPanel/InputSection.tsx b/client/src/components/parameterPanel/InputSection.tsx
index 6be71dde..8fae439b 100644
--- a/client/src/components/parameterPanel/InputSection.tsx
+++ b/client/src/components/parameterPanel/InputSection.tsx
@@ -722,6 +722,30 @@ const InputSection: React.FC<InputSectionProps> = ({ nodeId, visible = true }) =
crawler_type: 'string',
mode: 'string',
proxied: 'boolean'
+ },
+ // Filesystem & shell node schemas
+ fileRead: {
+ content: 'string',
+ file_path: 'string',
+ encoding: 'string'
+ },
+ fileModify: {
+ operation: 'string',
+ file_path: 'string',
+ occurrences: 'number'
+ },
+ shell: {
+ stdout: 'string',
+ exit_code: 'number',
+ truncated: 'boolean',
+ command: 'string'
+ },
+ fsSearch: {
+ path: 'string',
+ entries: 'array',
+ matches: 'array',
+ pattern: 'string',
+ count: 'number'
}
};
@@ -780,6 +804,9 @@ const InputSection: React.FC<InputSectionProps> = ({ nodeId, visible = true }) =
// Crawlee web scraping node detection
const isCrawlee = nodeType === 'crawleeScraper';
+ // Filesystem & shell node detection
+ const isFilesystemNode = ['fileRead', 'fileModify', 'shell', 'fsSearch'].includes(nodeType);
+
// Select appropriate schema
if (isAndroidLocation) {
outputSchema = sampleSchemas.androidLocation;
@@ -810,6 +837,7 @@ const InputSection: React.FC<InputSectionProps> = ({ nodeId, visible = true }) =
isApify ? sampleSchemas.apify :
isSearchNode ? sampleSchemas.search :
isCrawlee ? sampleSchemas.crawlee :
+ isFilesystemNode ? (sampleSchemas[nodeType as keyof typeof sampleSchemas] || { data: 'any' }) :
{ data: 'any' };
}
diff --git a/client/src/components/ui/NodeOutputPanel.tsx b/client/src/components/ui/NodeOutputPanel.tsx
index adc62a7a..746925af 100644
--- a/client/src/components/ui/NodeOutputPanel.tsx
+++ b/client/src/components/ui/NodeOutputPanel.tsx
@@ -186,6 +186,32 @@ const NodeOutputPanel: React.FC<NodeOutputPanelProps> = ({
type StructuredOutput = AndroidOutput | WhatsAppHistoryOutput | MapsNearbyOutput | MapsGeocodeOutput | MapsCreateOutput | SearchResultsOutput;
// Extract the main response text from execution results
+ const formatFilesystemOutput = (r: any): string | null => {
+ if (!r) return null;
+ // fileRead
+ if (r.content && r.file_path) return `File: ${r.file_path}\n\n${r.content}`;
+ // fileModify write
+ if (r.operation === 'write' && r.file_path) return `Written: ${r.file_path}`;
+ // fileModify edit
+ if (r.operation === 'edit' && r.file_path) return `Edited: ${r.file_path} (${r.occurrences || 1} replacement${(r.occurrences || 1) > 1 ? 's' : ''})`;
+ // shell
+ if (r.command !== undefined && r.stdout !== undefined) {
+ return `$ ${r.command}\n[${r.exit_code === 0 ? 'OK' : `Exit ${r.exit_code}`}]\n\n${r.stdout || '(no output)'}`;
+ }
+ // fsSearch ls
+ if (r.entries && Array.isArray(r.entries)) {
+ const lines = r.entries.map((e: any) => `${e.type === 'dir' ? '[DIR]' : ' '} ${e.name}${e.size != null ? ` (${e.size}b)` : ''}`);
+ return `${r.path || '.'} (${r.count || r.entries.length} items)\n\n${lines.join('\n')}`;
+ }
+ // fsSearch glob/grep
+ if (r.matches && Array.isArray(r.matches)) {
+ if (r.matches.length === 0) return `No matches for "${r.pattern}"`;
+ const lines = r.matches.slice(0, 50).map((m: any) => m.line ? `${m.path}:${m.line}: ${m.text}` : (m.path || JSON.stringify(m)));
+ return `${r.count || r.matches.length} match(es) for "${r.pattern}"\n\n${lines.join('\n')}${r.count > 50 ? `\n... and ${r.count - 50} more` : ''}`;
+ }
+ return null;
+ };
+
const getMainResponse = (result: ExecutionResult): string | StructuredOutput | null => {
const data = getOutputData(result);
@@ -193,6 +219,10 @@ const NodeOutputPanel: React.FC<NodeOutputPanelProps> = ({
if (data?.output !== undefined) {
return typeof data.output === 'string' ? data.output : JSON.stringify(data.output, null, 2);
}
+ // Filesystem/shell nodes
+ const fsOut = formatFilesystemOutput(data?.result) || formatFilesystemOutput(data);
+ if (fsOut) return fsOut;
+
if (data?.result?.response) return data.result.response;
if (data?.response) return data.response;
if (data?.result?.text) return data.result.text;
@@ -1337,6 +1367,26 @@ const NodeOutputPanel: React.FC<NodeOutputPanelProps> = ({
</div>
)}
+ {/* Agent Execution Metadata */}
+ {(() => {
+ const r = outputData?.result || outputData;
+ if (!r?.provider && !r?.agent_type) return null;
+ const tags: [string, string, string][] = [];
+ if (r.provider) tags.push([r.provider, 'cyan', 'Provider']);
+ if (r.model) tags.push([r.model, 'purple', 'Model']);
+ if (r.agent_type) tags.push([r.agent_type.replace(/_/g, ' '), 'green', 'Type']);
+ if (r.iterations > 1) tags.push([`${r.iterations} iterations`, 'orange', '']);
+ if (r.messages_count) tags.push([`${r.messages_count} msgs`, 'default', '']);
+ if (r.tools?.count) tags.push([`${r.tools.count} tool(s)`, 'magenta', '']);
+ if (r.skills?.count) tags.push([`${r.skills.count} skill(s)`, 'blue', '']);
+ if (r.memory?.session_id) tags.push([`${r.memory.history_loaded} history`, 'gold', '']);
+ return (
+ <Space wrap size={[4, 4]} style={{ marginBottom: theme.spacing.md }}>
+ {tags.map(([val, color], i) => <Tag key={i} color={color}>{val}</Tag>)}
+ </Space>
+ );
+ })()}
+
{/* JSON Output Toggle */}
<div style={{
backgroundColor: theme.colors.backgroundElevated,
diff --git a/client/src/components/ui/OutputDisplayPanel.tsx b/client/src/components/ui/OutputDisplayPanel.tsx
index 684b0a70..5e03c550 100644
--- a/client/src/components/ui/OutputDisplayPanel.tsx
+++ b/client/src/components/ui/OutputDisplayPanel.tsx
@@ -32,9 +32,60 @@ const OutputDisplayPanel: React.FC<OutputDisplayPanelProps> = ({ results, onClea
return { message: 'No output data' };
};
+ // Format filesystem/shell results into readable output
+ const formatFilesystemOutput = (data: any, nodeType?: string): string | null => {
+ const r = data?.result || data;
+ if (!r) return null;
+
+ // fileRead: show file content
+ if (r.content && r.file_path) {
+ return `File: ${r.file_path}\n\n${r.content}`;
+ }
+
+ // fileModify: show operation result
+ if (r.operation === 'write' && r.file_path) {
+ return `Written: ${r.file_path}`;
+ }
+ if (r.operation === 'edit' && r.file_path) {
+ return `Edited: ${r.file_path} (${r.occurrences || 1} replacement${(r.occurrences || 1) > 1 ? 's' : ''})`;
+ }
+
+ // shell: show stdout with exit code
+ if (r.command !== undefined && r.stdout !== undefined) {
+ const status = r.exit_code === 0 ? 'OK' : `Exit ${r.exit_code}`;
+ const output = r.stdout || '(no output)';
+ return `$ ${r.command}\n[${status}]\n\n${output}`;
+ }
+
+ // fsSearch ls: show directory listing
+ if (r.entries && Array.isArray(r.entries)) {
+ const lines = r.entries.map((e: any) =>
+ `${e.type === 'dir' ? '[DIR]' : ' '} ${e.name}${e.size != null ? ` (${e.size} bytes)` : ''}`
+ );
+ return `${r.path || '.'} (${r.count || r.entries.length} items)\n\n${lines.join('\n')}`;
+ }
+
+ // fsSearch glob/grep: show matches
+ if (r.matches && Array.isArray(r.matches)) {
+ if (r.matches.length === 0) return `No matches for "${r.pattern}"`;
+ const lines = r.matches.slice(0, 50).map((m: any) =>
+ m.line ? `${m.path}:${m.line}: ${m.text}` : (m.path || JSON.stringify(m))
+ );
+ const suffix = r.count > 50 ? `\n... and ${r.count - 50} more` : '';
+ return `${r.count || r.matches.length} match${(r.count || r.matches.length) > 1 ? 'es' : ''} for "${r.pattern}"\n\n${lines.join('\n')}${suffix}`;
+ }
+
+ return null;
+ };
+
// Extract the main response text from AI results
const getMainResponse = (result: ExecutionResult): string | null => {
const data = getExecutionData(result);
+
+ // Filesystem/shell nodes
+ const fsOutput = formatFilesystemOutput(data, result.nodeType);
+ if (fsOutput) return fsOutput;
+
// Handle nested response structure
if (data?.result?.response) return data.result.response;
if (data?.response) return data.response;
diff --git a/client/src/nodeDefinitions.ts b/client/src/nodeDefinitions.ts
index 498b2997..83aed314 100644
--- a/client/src/nodeDefinitions.ts
+++ b/client/src/nodeDefinitions.ts
@@ -25,6 +25,7 @@ import { searchNodes, SEARCH_NODE_TYPES } from './nodeDefinitions/searchNodes';
import { googleWorkspaceNodes, GOOGLE_WORKSPACE_NODE_TYPES } from './nodeDefinitions/googleWorkspaceNodes';
import { proxyNodes, PROXY_NODE_TYPES } from './nodeDefinitions/proxyNodes';
import { crawleeNodes, CRAWLEE_NODE_TYPES } from './nodeDefinitions/crawleeNodes';
+import { filesystemNodes, FILESYSTEM_NODE_TYPES } from './nodeDefinitions/filesystemNodes';
// ============================================================================
// MAIN NODE REGISTRY - Combining all modular definitions
@@ -53,7 +54,8 @@ export const nodeDefinitions: Record<string, INodeTypeDescription> = {
...searchNodes,
...googleWorkspaceNodes,
...proxyNodes,
- ...crawleeNodes
+ ...crawleeNodes,
+ ...filesystemNodes
};
// ============================================================================
@@ -154,5 +156,9 @@ export const CRAWLEE_NODES = [
...CRAWLEE_NODE_TYPES
];
+export const FILESYSTEM_NODES = [
+ ...FILESYSTEM_NODE_TYPES
+];
+
// Re-export types and utilities from modular files for external access
export { createBaseChatModel } from './nodeDefinitions/aiModelNodes';
diff --git a/client/src/nodeDefinitions/filesystemNodes.ts b/client/src/nodeDefinitions/filesystemNodes.ts
new file mode 100644
index 00000000..d3249df7
--- /dev/null
+++ b/client/src/nodeDefinitions/filesystemNodes.ts
@@ -0,0 +1,208 @@
+// Filesystem & Shell Tool Nodes - Dual-purpose (workflow node + AI agent tool)
+import { INodeTypeDescription, NodeConnectionType } from '../types/INodeProperties';
+
+export const filesystemNodes: Record<string, INodeTypeDescription> = {
+ fileRead: {
+ displayName: 'File Read',
+ name: 'fileRead',
+ icon: '\u{1F4C4}',
+ group: ['utility', 'tool'],
+ version: 1,
+ subtitle: 'Read File',
+ description: 'Read file contents with line numbers and pagination. Works as workflow node or AI agent tool.',
+ defaults: { name: 'File Read', color: '#8be9fd' },
+ inputs: [{ name: 'main', displayName: 'Input', type: 'main' as NodeConnectionType, description: 'Input data' }],
+ outputs: [
+ { name: 'main', displayName: 'Output', type: 'main' as NodeConnectionType, description: 'File contents' },
+ { name: 'tool', displayName: 'Tool', type: 'main' as NodeConnectionType, description: 'Connect to AI Agent tool handle' },
+ ],
+ properties: [
+ {
+ displayName: 'File Path',
+ name: 'file_path',
+ type: 'string' as any,
+ default: '',
+ required: true,
+ description: 'Path to the file to read',
+ },
+ {
+ displayName: 'Offset',
+ name: 'offset',
+ type: 'number' as any,
+ default: 0,
+ typeOptions: { minValue: 0 },
+ description: 'Line number to start reading from (0-indexed)',
+ },
+ {
+ displayName: 'Limit',
+ name: 'limit',
+ type: 'number' as any,
+ default: 100,
+ typeOptions: { minValue: 1, maxValue: 10000 },
+ description: 'Maximum number of lines to read',
+ },
+ ],
+ },
+
+ fileModify: {
+ displayName: 'File Modify',
+ name: 'fileModify',
+ icon: '\u{270F}\u{FE0F}',
+ group: ['utility', 'tool'],
+ version: 1,
+ subtitle: 'Write / Edit File',
+ description: 'Write a new file or edit an existing file with string replacement. Works as workflow node or AI agent tool.',
+ defaults: { name: 'File Modify', color: '#50fa7b' },
+ inputs: [{ name: 'main', displayName: 'Input', type: 'main' as NodeConnectionType, description: 'Input data' }],
+ outputs: [
+ { name: 'main', displayName: 'Output', type: 'main' as NodeConnectionType, description: 'Operation result' },
+ { name: 'tool', displayName: 'Tool', type: 'main' as NodeConnectionType, description: 'Connect to AI Agent tool handle' },
+ ],
+ properties: [
+ {
+ displayName: 'Operation',
+ name: 'operation',
+ type: 'options' as any,
+ default: 'write',
+ options: [
+ { name: 'Write', value: 'write' },
+ { name: 'Edit', value: 'edit' },
+ ],
+ description: 'Write creates/overwrites a file. Edit performs string replacement.',
+ },
+ {
+ displayName: 'File Path',
+ name: 'file_path',
+ type: 'string' as any,
+ default: '',
+ required: true,
+ description: 'Path to the file',
+ },
+ {
+ displayName: 'Content',
+ name: 'content',
+ type: 'string' as any,
+ default: '',
+ typeOptions: { rows: 5 },
+ description: 'File content to write',
+ displayOptions: { show: { operation: ['write'] } },
+ },
+ {
+ displayName: 'Old String',
+ name: 'old_string',
+ type: 'string' as any,
+ default: '',
+ typeOptions: { rows: 3 },
+ description: 'Exact text to find and replace',
+ displayOptions: { show: { operation: ['edit'] } },
+ },
+ {
+ displayName: 'New String',
+ name: 'new_string',
+ type: 'string' as any,
+ default: '',
+ typeOptions: { rows: 3 },
+ description: 'Text to replace old_string with',
+ displayOptions: { show: { operation: ['edit'] } },
+ },
+ {
+ displayName: 'Replace All',
+ name: 'replace_all',
+ type: 'boolean' as any,
+ default: false,
+ description: 'Replace all occurrences (default: first only, old_string must be unique)',
+ displayOptions: { show: { operation: ['edit'] } },
+ },
+ ],
+ },
+
+ shell: {
+ displayName: 'Shell',
+ name: 'shell',
+ icon: '\u{1F4BB}',
+ group: ['utility', 'tool'],
+ version: 1,
+ subtitle: 'Execute Command',
+ description: 'Execute shell commands and return stdout, stderr, and exit code. Works as workflow node or AI agent tool.',
+ defaults: { name: 'Shell', color: '#ff79c6' },
+ inputs: [{ name: 'main', displayName: 'Input', type: 'main' as NodeConnectionType, description: 'Input data' }],
+ outputs: [
+ { name: 'main', displayName: 'Output', type: 'main' as NodeConnectionType, description: 'Command output' },
+ { name: 'tool', displayName: 'Tool', type: 'main' as NodeConnectionType, description: 'Connect to AI Agent tool handle' },
+ ],
+ properties: [
+ {
+ displayName: 'Command',
+ name: 'command',
+ type: 'string' as any,
+ default: '',
+ required: true,
+ typeOptions: { rows: 3 },
+ description: 'Shell command to execute',
+ },
+ {
+ displayName: 'Timeout (seconds)',
+ name: 'timeout',
+ type: 'number' as any,
+ default: 30,
+ typeOptions: { minValue: 1, maxValue: 300 },
+ description: 'Maximum execution time in seconds',
+ },
+ ],
+ },
+
+ fsSearch: {
+ displayName: 'FS Search',
+ name: 'fsSearch',
+ icon: '\u{1F50D}',
+ group: ['utility', 'tool'],
+ version: 1,
+ subtitle: 'List / Glob / Grep',
+ description: 'Search the filesystem: list directories, glob pattern match, or grep file contents. Works as workflow node or AI agent tool.',
+ defaults: { name: 'FS Search', color: '#f1fa8c' },
+ inputs: [{ name: 'main', displayName: 'Input', type: 'main' as NodeConnectionType, description: 'Input data' }],
+ outputs: [
+ { name: 'main', displayName: 'Output', type: 'main' as NodeConnectionType, description: 'Search results' },
+ { name: 'tool', displayName: 'Tool', type: 'main' as NodeConnectionType, description: 'Connect to AI Agent tool handle' },
+ ],
+ properties: [
+ {
+ displayName: 'Mode',
+ name: 'mode',
+ type: 'options' as any,
+ default: 'ls',
+ options: [
+ { name: 'List Directory', value: 'ls' },
+ { name: 'Glob Pattern', value: 'glob' },
+ { name: 'Grep Contents', value: 'grep' },
+ ],
+ description: 'Search mode: list directory, glob file patterns, or grep file contents',
+ },
+ {
+ displayName: 'Path',
+ name: 'path',
+ type: 'string' as any,
+ default: '.',
+ description: 'Directory path to search in',
+ },
+ {
+ displayName: 'Pattern',
+ name: 'pattern',
+ type: 'string' as any,
+ default: '',
+ description: 'Glob pattern (e.g., **/*.py) or grep search text',
+ displayOptions: { show: { mode: ['glob', 'grep'] } },
+ },
+ {
+ displayName: 'File Filter',
+ name: 'file_filter',
+ type: 'string' as any,
+ default: '',
+ description: 'Glob pattern to filter which files to grep (e.g., *.py)',
+ displayOptions: { show: { mode: ['grep'] } },
+ },
+ ],
+ },
+};
+
+export const FILESYSTEM_NODE_TYPES = ['fileRead', 'fileModify', 'shell', 'fsSearch'];
diff --git a/client/src/services/executionService.ts b/client/src/services/executionService.ts
index 28fde06b..528a52ef 100644
--- a/client/src/services/executionService.ts
+++ b/client/src/services/executionService.ts
@@ -237,7 +237,12 @@ export class ExecutionService {
// Proxy Nodes
'proxyRequest',
'proxyConfig',
- 'proxyStatus'
+ 'proxyStatus',
+ // Filesystem & Shell
+ 'fileRead',
+ 'fileModify',
+ 'shell',
+ 'fsSearch'
];
return supportedTypes.includes(nodeType);
diff --git a/docs-internal/deep_agent.md b/docs-internal/deep_agent.md
index 220950d8..4bc8ca5b 100644
--- a/docs-internal/deep_agent.md
+++ b/docs-internal/deep_agent.md
@@ -357,6 +357,21 @@ Matches `execute_chat_agent` format for frontend compatibility:
---
+## Filesystem & Shell Tool Nodes
+
+MachinaOs provides 4 dual-purpose tool nodes that delegate to `deepagents.backends.LocalShellBackend`:
+
+| Node | Tool Name | Description |
+|------|-----------|-------------|
+| `fileRead` | `file_read` | Read file contents with pagination |
+| `fileModify` | `file_modify` | Write new files or edit existing files (string replacement) |
+| `shell` | `shell_execute` | Execute shell commands with timeout |
+| `fsSearch` | `fs_search` | List directories, glob pattern match, or grep file contents |
+
+These work as standalone workflow nodes AND as AI agent tools when connected to any agent's `input-tools` handle. Defined in `client/src/nodeDefinitions/filesystemNodes.ts`, handlers in `server/services/handlers/filesystem.py`.
+
+---
+
## Comparison with Other Agent Types
| Aspect | chatAgent | deep_agent | claude_code_agent | rlm_agent |
diff --git a/server/core/config.py b/server/core/config.py
index adcd8c4b..77f62c6f 100644
--- a/server/core/config.py
+++ b/server/core/config.py
@@ -64,6 +64,9 @@ class Settings(BaseSettings):
nodejs_executor_timeout: int = Field(default=30, env="NODEJS_EXECUTOR_TIMEOUT", ge=5, le=300)
nodejs_executor_port: int = Field(default=3020, env="NODEJS_EXECUTOR_PORT", ge=1024, le=65535)
+ # Deep Agent filesystem root (defaults to server working directory)
+ deep_agent_workspace: str = Field(default="", env="DEEP_AGENT_WORKSPACE")
+
# AI Proxy Configuration (Ollama-style proxy)
ai_proxy_default_port: int = Field(default=11434, env="AI_PROXY_DEFAULT_PORT")
diff --git a/server/services/agents/service.py b/server/services/agents/service.py
index 515a5739..7c4257cd 100644
--- a/server/services/agents/service.py
+++ b/server/services/agents/service.py
@@ -145,17 +145,22 @@ class DeepAgentService:
input_messages.append({"role": "user", "content": prompt})
- # === Create and invoke deep agent ===
- from deepagents import create_deep_agent
+ # === Create and invoke agent ===
+ # Use langchain.agents.create_agent directly (not create_deep_agent)
+ # to avoid built-in middleware (filesystem, todo, subagent) that bypasses
+ # MachinaOs tool nodes. Only connected MachinaOs tools are used.
+ from langchain.agents import create_agent
+ from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
+
max_turns = int(parameters.get('maxTurns', DEFAULT_MAX_TURNS))
await broadcast_status("executing", {"message": f"Running Deep Agent ({provider}/{model})...", "tool_count": len(executable_tools)})
- agent = create_deep_agent(
+ agent = create_agent(
model=chat_model,
- tools=executable_tools or None,
+ tools=executable_tools or [],
system_prompt=system_message,
- subagents=subagents,
+ middleware=[PatchToolCallsMiddleware()],
)
result = await agent.ainvoke(
{"messages": input_messages},
diff --git a/server/services/ai.py b/server/services/ai.py
index eabc168f..268f7714 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -2437,6 +2437,11 @@ class AIService:
'taskManager': 'task_manager',
'timer': 'timer',
'cronScheduler': 'cron_scheduler',
+ # Filesystem and shell tools (deepagents backends)
+ 'fileRead': 'file_read',
+ 'fileModify': 'file_modify',
+ 'shell': 'shell_execute',
+ 'fsSearch': 'fs_search',
# Built-in check tool for delegation results
'_builtin_check_delegated_tasks': 'check_delegated_tasks',
# Agent delegation tools
@@ -2506,6 +2511,11 @@ class AIService:
'taskManager': 'Track delegated sub-agent tasks. Operations: list_tasks (see all tasks), get_task (check specific task status/result), mark_done (cleanup completed tasks).',
'timer': 'Wait/sleep for a specified duration. Specify duration (1-3600) and unit (seconds, minutes, or hours). Returns timestamp and elapsed time after waiting.',
'cronScheduler': 'Schedule a delayed or recurring execution. Supports seconds, minutes, hours, daily, weekly, monthly frequencies with timezone. Use frequency to set schedule type, then set the relevant interval/time parameters.',
+ # Filesystem and shell tools (deepagents backends)
+ 'fileRead': 'Read file contents with pagination. Returns line-numbered text.',
+ 'fileModify': 'Write a new file or edit an existing file with string replacement. Operations: write (create/overwrite), edit (find and replace).',
+ 'shell': 'Execute a shell command. Returns stdout, stderr, and exit code.',
+ 'fsSearch': 'Search the filesystem. Modes: ls (list directory), glob (pattern match files), grep (search file contents for text).',
# Built-in check tool for delegation results
'_builtin_check_delegated_tasks': 'Check status and retrieve results of previously delegated tasks.',
# Agent delegation tools - ONE-SHOT fire-and-forget pattern
@@ -3176,6 +3186,42 @@ class AIService:
return NearbyPlacesSchema
+ # Filesystem and shell tool schemas (deepagents backends)
+ if node_type == 'fileRead':
+ class FileReadSchema(BaseModel):
+ """Read file contents with pagination."""
+ file_path: str = Field(description="Path to the file to read")
+ offset: int = Field(default=0, description="Line number to start from (0-indexed)")
+ limit: int = Field(default=100, description="Maximum number of lines to read")
+ return FileReadSchema
+
+ if node_type == 'fileModify':
+ class FileModifySchema(BaseModel):
+ """Write a new file or edit an existing file."""
+ operation: str = Field(description="Operation: 'write' (create/overwrite) or 'edit' (find and replace)")
+ file_path: str = Field(description="Path to the file")
+ content: Optional[str] = Field(default=None, description="File content (for write operation)")
+ old_string: Optional[str] = Field(default=None, description="Text to find (for edit operation)")
+ new_string: Optional[str] = Field(default=None, description="Replacement text (for edit operation)")
+ replace_all: bool = Field(default=False, description="Replace all occurrences (for edit operation)")
+ return FileModifySchema
+
+ if node_type == 'shell':
+ class ShellSchema(BaseModel):
+ """Execute a shell command."""
+ command: str = Field(description="Shell command to execute")
+ timeout: int = Field(default=30, description="Timeout in seconds (1-300)")
+ return ShellSchema
+
+ if node_type == 'fsSearch':
+ class FsSearchSchema(BaseModel):
+ """Search the filesystem: list directory, glob pattern match, or grep file contents."""
+ mode: str = Field(default="ls", description="Mode: 'ls' (list dir), 'glob' (pattern match), 'grep' (search contents)")
+ path: str = Field(default=".", description="Directory path to search in")
+ pattern: Optional[str] = Field(default=None, description="Glob pattern or grep search text (required for glob/grep)")
+ file_filter: Optional[str] = Field(default=None, description="Glob to filter files for grep (e.g. '*.py')")
+ return FsSearchSchema
+
# Task Manager schema (dual-purpose: AI tool + workflow node)
if node_type == 'taskManager':
class TaskManagerSchema(BaseModel):
diff --git a/server/services/handlers/__init__.py b/server/services/handlers/__init__.py
index e95dc8dd..05fff972 100644
--- a/server/services/handlers/__init__.py
+++ b/server/services/handlers/__init__.py
@@ -120,6 +120,14 @@ from .rlm import handle_rlm_agent
# Deep Agent handler
from .deep_agent import handle_deep_agent
+# Filesystem and shell handlers
+from .filesystem import (
+ handle_file_read,
+ handle_file_modify,
+ handle_shell,
+ handle_fs_search,
+)
+
# Tool execution handlers (for AI Agent tool calling)
from .tools import (
execute_tool,
@@ -191,6 +199,11 @@ __all__ = [
'handle_rlm_agent',
# Deep Agent
'handle_deep_agent',
+ # Filesystem & Shell
+ 'handle_file_read',
+ 'handle_file_modify',
+ 'handle_shell',
+ 'handle_fs_search',
# Tools
'execute_tool',
'handle_task_manager',
diff --git a/server/services/handlers/filesystem.py b/server/services/handlers/filesystem.py
new file mode 100644
index 00000000..73378fd8
--- /dev/null
+++ b/server/services/handlers/filesystem.py
@@ -0,0 +1,153 @@
+"""Filesystem and shell handlers - delegates to deepagents backends.
+
+Uses deepagents.backends.LocalShellBackend methods:
+ read() -> str, write() -> WriteResult, edit() -> EditResult,
+ ls_info() -> list[FileInfo], glob_info() -> list[FileInfo],
+ grep_raw() -> list[GrepMatch] | str, execute() -> ExecuteResponse.
+"""
+
+import os
+from typing import Any, Dict
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _get_backend(parameters: Dict[str, Any]):
+ """Get a LocalShellBackend rooted at configured workspace."""
+ from deepagents.backends import LocalShellBackend
+ from core.container import container
+ root = parameters.get('working_directory') or container.settings().deep_agent_workspace or os.getcwd()
+ return LocalShellBackend(root_dir=root, virtual_mode=True)
+
+
+async def handle_file_read(
+ node_id: str, node_type: str, parameters: Dict[str, Any], context: Dict[str, Any],
+) -> Dict[str, Any]:
+ """Read file via backend.read() which returns str content directly."""
+ file_path = parameters.get('file_path', '')
+ if not file_path:
+ return {"success": False, "node_id": node_id, "error": "file_path is required"}
+
+ try:
+ backend = _get_backend(parameters)
+ content = backend.read(file_path, offset=int(parameters.get('offset', 0)), limit=int(parameters.get('limit', 100)))
+ return {
+ "success": True, "node_id": node_id,
+ "result": {"content": content, "file_path": file_path},
+ }
+ except Exception as e:
+ return {"success": False, "node_id": node_id, "error": str(e)}
+
+
+async def handle_file_modify(
+ node_id: str, node_type: str, parameters: Dict[str, Any], context: Dict[str, Any],
+) -> Dict[str, Any]:
+ """Write or edit file via backend.write()/edit()."""
+ operation = parameters.get('operation', 'write')
+ file_path = parameters.get('file_path', '')
+ if not file_path:
+ return {"success": False, "node_id": node_id, "error": "file_path is required"}
+
+ try:
+ backend = _get_backend(parameters)
+
+ if operation == 'write':
+ content = parameters.get('content', '')
+ result = backend.write(file_path, content)
+ if result.error:
+ return {"success": False, "node_id": node_id, "error": result.error}
+ return {
+ "success": True, "node_id": node_id,
+ "result": {"operation": "write", "file_path": result.path or file_path},
+ }
+
+ elif operation == 'edit':
+ old_string = parameters.get('old_string', '')
+ new_string = parameters.get('new_string', '')
+ replace_all = parameters.get('replace_all', False)
+ if not old_string:
+ return {"success": False, "node_id": node_id, "error": "old_string is required for edit"}
+
+ result = backend.edit(file_path, old_string, new_string, replace_all=replace_all)
+ if result.error:
+ return {"success": False, "node_id": node_id, "error": result.error}
+ return {
+ "success": True, "node_id": node_id,
+ "result": {"operation": "edit", "file_path": result.path or file_path, "occurrences": result.occurrences},
+ }
+
+ return {"success": False, "node_id": node_id, "error": f"Unknown operation: {operation}"}
+ except Exception as e:
+ return {"success": False, "node_id": node_id, "error": str(e)}
+
+
+async def handle_shell(
+ node_id: str, node_type: str, parameters: Dict[str, Any], context: Dict[str, Any],
+) -> Dict[str, Any]:
+ """Execute shell command via backend.execute()."""
+ command = parameters.get('command', '')
+ if not command:
+ return {"success": False, "node_id": node_id, "error": "command is required"}
+
+ try:
+ timeout = int(parameters.get('timeout', 30))
+ backend = _get_backend(parameters)
+ result = backend.execute(command, timeout=timeout)
+ return {
+ "success": True, "node_id": node_id,
+ "result": {
+ "stdout": result.output,
+ "exit_code": result.exit_code,
+ "truncated": result.truncated,
+ "command": command,
+ },
+ }
+ except Exception as e:
+ return {"success": False, "node_id": node_id, "error": str(e)}
+
+
+async def handle_fs_search(
+ node_id: str, node_type: str, parameters: Dict[str, Any], context: Dict[str, Any],
+) -> Dict[str, Any]:
+ """Search filesystem via backend.ls_info()/glob_info()/grep_raw()."""
+ mode = parameters.get('mode', 'ls')
+ path = parameters.get('path', '.')
+ pattern = parameters.get('pattern', '')
+
+ try:
+ backend = _get_backend(parameters)
+
+ if mode == 'ls':
+ entries = backend.ls_info(path)
+ return {
+ "success": True, "node_id": node_id,
+ "result": {"path": path, "entries": [dict(e) for e in entries], "count": len(entries)},
+ }
+
+ elif mode == 'glob':
+ if not pattern:
+ return {"success": False, "node_id": node_id, "error": "pattern is required for glob mode"}
+ matches = backend.glob_info(pattern, path=path)
+ return {
+ "success": True, "node_id": node_id,
+ "result": {"path": path, "pattern": pattern, "matches": [dict(m) for m in matches], "count": len(matches)},
+ }
+
+ elif mode == 'grep':
+ if not pattern:
+ return {"success": False, "node_id": node_id, "error": "pattern is required for grep mode"}
+ file_filter = parameters.get('file_filter') or None
+ result = backend.grep_raw(pattern, path=path, glob=file_filter)
+ # grep_raw returns list[GrepMatch] or str (error message)
+ if isinstance(result, str):
+ return {"success": False, "node_id": node_id, "error": result}
+ return {
+ "success": True, "node_id": node_id,
+ "result": {"path": path, "pattern": pattern, "matches": [dict(m) for m in result], "count": len(result)},
+ }
+
+ return {"success": False, "node_id": node_id, "error": f"Unknown mode: {mode}"}
+ except Exception as e:
+ return {"success": False, "node_id": node_id, "error": str(e)}
diff --git a/server/services/handlers/tools.py b/server/services/handlers/tools.py
index f492ea67..ebea7f2d 100644
--- a/server/services/handlers/tools.py
+++ b/server/services/handlers/tools.py
@@ -74,6 +74,23 @@ async def execute_tool(tool_name: str, tool_args: Dict[str, Any],
if node_type == 'duckduckgoSearch':
return await _execute_duckduckgo_search(tool_args, config.get('parameters', {}))
+ # Filesystem and shell tools (deepagents backends)
+ if node_type in ('fileRead', 'fileModify', 'shell', 'fsSearch'):
+ from services.handlers.filesystem import handle_file_read, handle_file_modify, handle_shell, handle_fs_search
+ params = {**config.get('parameters', {}), **tool_args}
+ handler_map = {
+ 'fileRead': handle_file_read,
+ 'fileModify': handle_file_modify,
+ 'shell': handle_shell,
+ 'fsSearch': handle_fs_search,
+ }
+ return await handler_map[node_type](
+ node_id=config.get('node_id', f'tool_{node_type}'),
+ node_type=node_type,
+ parameters=params,
+ context={},
+ )
+
# Timer tool (dual-purpose: workflow node + AI tool)
# LLM fills duration/unit via Pydantic schema; calls existing handle_timer handler
if node_type == 'timer':
diff --git a/server/services/node_executor.py b/server/services/node_executor.py
index 9bd59d46..f6993b40 100644
--- a/server/services/node_executor.py
+++ b/server/services/node_executor.py
@@ -46,6 +46,7 @@ from services.handlers.telegram import handle_telegram_send
from services.handlers.apify import handle_apify_actor
from services.handlers.crawlee import handle_crawlee_scraper
from services.handlers.proxy import handle_proxy_request, handle_proxy_status, handle_proxy_config
+from services.handlers.filesystem import handle_file_read, handle_file_modify, handle_shell, handle_fs_search
# Consolidated Google Workspace handlers (6 services with operation dispatchers)
from services.handlers.gmail import handle_google_gmail, handle_gmail_receive
from services.handlers.calendar import handle_google_calendar
@@ -198,6 +199,11 @@ class NodeExecutor:
'proxyRequest': handle_proxy_request,
'proxyStatus': handle_proxy_status,
'proxyConfig': handle_proxy_config,
+ # Filesystem and shell nodes (deepagents backends)
+ 'fileRead': handle_file_read,
+ 'fileModify': handle_file_modify,
+ 'shell': handle_shell,
+ 'fsSearch': handle_fs_search,
# Note: 'console' handled in _dispatch with connected_outputs
}
diff --git a/server/skills/coding_agent/file-modify-skill/SKILL.md b/server/skills/coding_agent/file-modify-skill/SKILL.md
new file mode 100644
index 00000000..c16ae372
--- /dev/null
+++ b/server/skills/coding_agent/file-modify-skill/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: file-modify-skill
+description: Write new files or edit existing files with string replacement.
+allowed-tools: file_modify
+metadata:
+ author: machina
+ version: "1.0"
+ category: filesystem
+ icon: "\u270F\uFE0F"
+ color: "#50fa7b"
+---
+
+# File Modify Tool
+
+Write new files or edit existing files with exact string replacement. Uses deepagents filesystem backend.
+
+## file_modify Tool
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| operation | string | Yes | `write` (create/overwrite) or `edit` (find and replace) |
+| file_path | string | Yes | Path to the file |
+| content | string | If write | Full file content to write |
+| old_string | string | If edit | Exact text to find and replace |
+| new_string | string | If edit | Replacement text |
+| replace_all | boolean | No | Replace all occurrences (default: false, old_string must be unique) |
+
+### Examples
+
+**Write a new file:**
+```json
+{
+ "operation": "write",
+ "file_path": "/path/to/new_file.py",
+ "content": "print('hello world')"
+}
+```
+
+**Edit an existing file:**
+```json
+{
+ "operation": "edit",
+ "file_path": "/path/to/file.py",
+ "old_string": "def old_name():",
+ "new_string": "def new_name():"
+}
+```
+
+**Replace all occurrences:**
+```json
+{
+ "operation": "edit",
+ "file_path": "/path/to/file.py",
+ "old_string": "TODO",
+ "new_string": "DONE",
+ "replace_all": true
+}
+```
+
+### Response Format
+
+**Write:**
+```json
+{"operation": "write", "file_path": "/path/to/file.py"}
+```
+
+**Edit:**
+```json
+{"operation": "edit", "file_path": "/path/to/file.py", "occurrences": 1}
+```
+
+### Guidelines
+
+1. Use `write` to create new files or overwrite existing ones
+2. Use `edit` for surgical string replacement in existing files
+3. For edit: `old_string` must be unique in the file unless `replace_all` is true
+4. Prefer `edit` over `write` when modifying existing files
+5. Read the file first before editing to ensure correct context
diff --git a/server/skills/coding_agent/file-read-skill/SKILL.md b/server/skills/coding_agent/file-read-skill/SKILL.md
new file mode 100644
index 00000000..f628d90e
--- /dev/null
+++ b/server/skills/coding_agent/file-read-skill/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: file-read-skill
+description: Read file contents with line numbers and pagination support.
+allowed-tools: file_read
+metadata:
+ author: machina
+ version: "1.0"
+ category: filesystem
+ icon: "\U0001F4C4"
+ color: "#8be9fd"
+---
+
+# File Read Tool
+
+Read file contents with line-numbered output and pagination. Uses deepagents filesystem backend.
+
+## file_read Tool
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| file_path | string | Yes | Path to the file to read |
+| offset | int | No | Line number to start from, 0-indexed (default: 0) |
+| limit | int | No | Maximum lines to read (default: 100, max: 10000) |
+
+### Examples
+
+**Read a file:**
+```json
+{"file_path": "/path/to/file.py"}
+```
+
+**Read with pagination:**
+```json
+{"file_path": "/path/to/large_file.py", "offset": 100, "limit": 50}
+```
+
+### Response Format
+
+```json
+{
+ "content": "1\tline one\n2\tline two\n...",
+ "file_path": "/path/to/file.py",
+ "encoding": "utf-8"
+}
+```
+
+### Guidelines
+
+1. Use offset/limit for large files instead of reading everything
+2. File content is returned with line numbers (tab-separated)
+3. Binary files return base64-encoded content
diff --git a/server/skills/coding_agent/fs-search-skill/SKILL.md b/server/skills/coding_agent/fs-search-skill/SKILL.md
new file mode 100644
index 00000000..d31d23ac
--- /dev/null
+++ b/server/skills/coding_agent/fs-search-skill/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: fs-search-skill
+description: Search the filesystem with ls (list directory), glob (pattern match), or grep (search file contents).
+allowed-tools: fs_search
+metadata:
+ author: machina
+ version: "1.0"
+ category: filesystem
+ icon: "\U0001F50D"
+ color: "#f1fa8c"
+---
+
+# FS Search Tool
+
+Search the filesystem: list directories, glob pattern match files, or grep file contents. Uses deepagents filesystem backend.
+
+## fs_search Tool
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| mode | string | No | `ls` (list directory), `glob` (pattern match), `grep` (search contents). Default: `ls` |
+| path | string | No | Directory path to search in (default: `.`) |
+| pattern | string | If glob/grep | Glob pattern (e.g., `**/*.py`) or grep search text |
+| file_filter | string | No | Glob to filter files for grep mode (e.g., `*.py`) |
+
+### Examples
+
+**List directory:**
+```json
+{"mode": "ls", "path": "/path/to/project"}
+```
+
+**Find Python files:**
+```json
+{"mode": "glob", "path": ".", "pattern": "**/*.py"}
+```
+
+**Search for a function:**
+```json
+{"mode": "grep", "path": ".", "pattern": "def my_function", "file_filter": "*.py"}
+```
+
+**Find all config files:**
+```json
+{"mode": "glob", "path": "/etc", "pattern": "*.conf"}
+```
+
+### Response Format
+
+**ls mode:**
+```json
+{
+ "path": ".",
+ "entries": [
+ {"name": "src", "type": "dir", "size": null},
+ {"name": "README.md", "type": "file", "size": 1234}
+ ],
+ "count": 2
+}
+```
+
+**glob mode:**
+```json
+{
+ "path": ".",
+ "pattern": "**/*.py",
+ "matches": [{"path": "src/main.py"}, {"path": "tests/test_main.py"}],
+ "count": 2
+}
+```
+
+**grep mode:**
+```json
+{
+ "path": ".",
+ "pattern": "def main",
+ "matches": [
+ {"path": "src/main.py", "line": 42, "text": "def main():"}
+ ],
+ "count": 1
+}
+```
+
+### Guidelines
+
+1. Use `ls` to explore directory structure
+2. Use `glob` to find files by name pattern (supports `**` recursive, `*` wildcard, `?` single char)
+3. Use `grep` to search file contents (literal text, not regex)
+4. Combine `grep` with `file_filter` to limit search scope
+5. Results are capped at 500 matches for grep mode
diff --git a/server/skills/coding_agent/shell-skill/SKILL.md b/server/skills/coding_agent/shell-skill/SKILL.md
new file mode 100644
index 00000000..6f625e80
--- /dev/null
+++ b/server/skills/coding_agent/shell-skill/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: shell-skill
+description: Execute shell commands and return stdout, stderr, and exit code.
+allowed-tools: shell_execute
+metadata:
+ author: machina
+ version: "1.0"
+ category: execution
+ icon: "\U0001F4BB"
+ color: "#ff79c6"
+---
+
+# Shell Tool
+
+Execute shell commands with timeout control. Uses deepagents LocalShellBackend.
+
+## shell_execute Tool
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| command | string | Yes | Shell command to execute |
+| timeout | int | No | Timeout in seconds (default: 30, max: 300) |
+
+### Examples
+
+**List files:**
+```json
+{"command": "ls -la /path/to/dir"}
+```
+
+**Run a script:**
+```json
+{"command": "python script.py --arg value", "timeout": 60}
+```
+
+**Check disk usage:**
+```json
+{"command": "df -h"}
+```
+
+**Install a package:**
+```json
+{"command": "pip install requests", "timeout": 120}
+```
+
+### Response Format
+
+```json
+{
+ "stdout": "command output here",
+ "exit_code": 0,
+ "truncated": false,
+ "command": "ls -la"
+}
+```
+
+### Guidelines
+
+1. Set appropriate timeouts for long-running commands
+2. Exit code 0 means success, non-zero means failure
+3. Check `truncated` flag -- output may be cut if too large
+4. Use absolute paths when possible
+5. Chain commands with `&&` for sequential execution
+6. Avoid interactive commands that require user input