Last updated: Aug 12, 2025, 08:12 AM UTC

Sasha Tools System - Complete Implementation Plan

Generated: 2025-08-06 UTC
Purpose: Comprehensive implementation plan for Sasha's markdown-defined tools system with permissions and activity logging
Audience: Development team implementing the Sasha tool system

Executive Summary

This document outlines the complete implementation plan for Sasha's revolutionary tool system where:

  • Tools are defined entirely in markdown files (no programming required)
  • An admin permission system controls tool availability
  • All operations are tracked in a comprehensive activity log
  • Natural language triggers execute sophisticated document operations

System Architecture

High-Level Architecture (Enhanced with LLxprt)

┌──────────────────────────────────────────────────────────┐
│                     User Interface                        │
│  Chat Input → Natural Language Processing → Tool Display  │
└────────────────────┬─────────────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────────────┐
│                    AI Service Layer                       │
│  Intent Detection → Context Loading → Confirmation Flow   │
└────────────────────┬─────────────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────────────┐
│              LLxprt Tool Orchestration Layer              │
│  JSON Schema → Handler Execution → Result Processing      │
│  (Shell/Python/JS handlers with structured invocation)    │
└────────────────────┬─────────────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────────────┐
│                   Tool Execution Layer                    │
│  Permission Check → Execute Handler → Activity Log        │
└────────────────────┬─────────────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────────────┐
│                    Storage Layer                          │
│  Tool Schemas │ Handlers │ Permissions │ Logs │ Output   │
└──────────────────────────────────────────────────────────┘

Core Components

1. Tool Definition System (Hybrid Approach)

  • JSON Schemas: /tools/schemas/*.json - Structured tool definitions for LLxprt
  • Handlers: /tools/handlers/* - Executable scripts (shell/Python/JS)
  • Documentation: /tools-docs/*.md - Human-readable tool descriptions
  • LLxprt Bridge: Orchestrates tool execution with structured invocation

2. Permission System

  • Configuration: /config/tool-permissions.json
  • Admin UI for enabling/disabling tools
  • Role-based access control
  • Risk level classification

3. Activity Logging

  • Storage: /logs/activity/YYYY-MM-DD.jsonl
  • Tracks all file system changes
  • Records external communications
  • Monitors tool usage and performance

4. Tool Executor

  • Parses markdown instructions
  • Validates permissions
  • Executes commands
  • Handles user confirmations

LLxprt Integration Architecture

How LLxprt Transforms Our Tool System

LLxprt provides a structured bridge between AI intent and tool execution:

  1. JSON-Defined Tools: Tools are defined as JSON schemas with parameters
  2. Handler Execution: Shell commands, Python functions, or JS modules
  3. Structured Invocation: AI calls tools with typed parameters
  4. Result Processing: Output returns to AI context for continued reasoning

Tool Definition Structure

/tools/
├── schemas/                 # JSON tool definitions
│   ├── read-file.json      # Schema with parameters
│   ├── search-web.json     
│   └── create-ppt.json     
├── handlers/               # Executable implementations
│   ├── read-file.sh       # Shell script handler
│   ├── search-web.py      # Python handler
│   └── create-ppt.py      
└── docs/                   # Human documentation
    └── *.md                # Markdown descriptions

Example Tool Flow

// 1. AI detects intent
User: "Read the project README"

// 2. LLxprt tool invocation
{
  "invoke_tool": {
    "tool_name": "read_file",
    "parameters": {
      "file_path": "README.md"
    }
  }
}

// 3. Handler execution
$ bash tools/handlers/read-file.sh README.md

// 4. Result returns to AI
{
  "success": true,
  "content": "[file contents]"
}

Tool Definition Formats

JSON Schema Format (for LLxprt execution)

{
  "name": "tool_name",
  "description": "What this tool does",
  "parameters": {
    "param1": {
      "type": "string",
      "description": "Description of parameter"
    },
    "param2": {
      "type": "integer",
      "description": "Description of parameter",
      "required": false
    }
  },
  "handler": {
    "type": "shell|python|javascript",
    "path": "tools/handlers/tool_name.sh"
  },
  "permissions": {
    "riskLevel": "low|medium|high|critical",
    "requiresConfirmation": true,
    "category": "creation|enhancement|utility"
  }
}

Markdown Documentation Format (for human reference)

# Tool Name

## Purpose
Clear description of what this tool accomplishes

## Natural Language Triggers
- "create a presentation about..."
- "generate slides for..."
- "make a PowerPoint..."

## Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| topic | string | Yes | The main topic or subject |
| slides | integer | No | Number of slides (default: 10) |
| theme | string | No | Visual theme to apply |

## Execution Flow
1. Validate input parameters
2. Generate content structure
3. Apply formatting and theme
4. Export to desired format
5. Save to workspace

## Example Usage
User: "Create a presentation about Q4 results with 15 slides"
Tool invokes: create_ppt with {topic: "Q4 results", slides: 15}

## Error Handling
- Missing required parameters → Request from user
- Invalid path → Use default workspace
- Export failure → Retry with alternative format

Tool Examples

Document Creation Tools

1. PowerPoint Creator (create-ppt-tool.md)

  • Creates presentation slides
  • Converts to PPTX/PDF formats
  • Supports multiple themes
  • Generates speaker notes

2. Excel Creator (create-excel-tool.md)

  • Generates spreadsheets with formulas
  • Creates charts and pivot tables
  • Exports to XLSX/CSV
  • Supports multiple sheets

3. Document Beautifier (beautify-document-tool.md)

  • Enhances markdown formatting
  • Adds visual elements (emojis, tables, charts)
  • Creates professional layouts
  • Generates HTML previews

4. Document Rewriter (rewrite-document-tool.md)

  • Rewrites for clarity/conciseness
  • Adjusts tone (professional/casual)
  • Improves readability scores
  • Preserves original backups

Permission System Design

Permission Configuration Schema

{
  "version": "1.0",
  "lastModified": "2025-08-06T10:00:00Z",
  "modifiedBy": "admin",
  "globalSettings": {
    "requireConfirmation": true,
    "auditLogging": true,
    "rateLimiting": {
      "enabled": true,
      "maxPerHour": 100
    }
  },
  "tools": [
    {
      "id": "tool-id",
      "enabled": true|false,
      "name": "Tool Name",
      "description": "What this tool does",
      "riskLevel": "low|medium|high|critical",
      "requiresConfirmation": true|false,
      "category": "creation|enhancement|utility",
      "permissions": {
        "allowedPaths": [],
        "restrictedPaths": [],
        "maxFileSizeMB": 10,
        "allowedFormats": []
      }
    }
  ],
  "userRoles": {
    "admin": {
      "canModifyPermissions": true,
      "canEnableAllTools": true
    },
    "user": {
      "canModifyPermissions": false,
      "allowedTools": ["list", "of", "tool", "ids"]
    }
  }
}

Risk Level Classifications

Level Color Description Examples
Low 🟢 Green Read-only or creates new files Create document, Generate report
Medium 🟡 Yellow Modifies existing files Beautify document, Rewrite content
High 🟠 Orange Deletes files or external communication Delete files, Send email
Critical 🔴 Red System commands or security-sensitive Execute code, Access credentials

Activity Logging System

Activity Log Schema

{
  // Metadata
  timestamp: "2025-08-06T10:30:00.123Z",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  userId: "user@example.com",
  userRole: "admin",
  
  // Action details
  action: "tool_execution",
  category: "file_system_write",
  tool: "create-ppt",
  
  // Execution details
  input: {
    trigger: "create a ppt about Q4 results",
    parameters: {
      topic: "Q4 Results",
      slides: 10,
      theme: "corporate"
    }
  },
  
  // Results
  output: {
    filesCreated: [
      "/workspace/presentations/q4-results.pptx",
      "/workspace/presentations/q4-results.pdf"
    ],
    filesModified: [],
    filesDeleted: [],
    bytesWritten: 245678,
    externalCalls: []
  },
  
  // Metadata
  duration: 3456,
  success: true,
  error: null,
  confirmedByUser: true,
  riskLevel: "low"
}

Event Categories

File System Operations

  • file_created - New file created
  • file_modified - Existing file changed
  • file_deleted - File removed
  • directory_created - New folder created
  • directory_deleted - Folder removed

External Communications

  • email_sent - Email dispatched
  • webhook_called - External webhook triggered
  • api_request - External API called
  • mcp_connection - MCP server connected
  • mcp_command - MCP command executed

Tool Operations

  • tool_started - Tool execution began
  • tool_completed - Tool finished successfully
  • tool_failed - Tool encountered error
  • tool_cancelled - User cancelled execution
  • tool_permission_denied - Tool blocked by permissions

System Operations

  • bash_command - Shell command executed
  • python_script - Python code run
  • npm_command - NPM command executed
  • git_operation - Git command executed

Administrative Actions

  • permission_changed - Tool permission modified
  • tool_enabled - Tool activated
  • tool_disabled - Tool deactivated
  • role_modified - User role changed
  • config_updated - System configuration changed

Activity Log Storage

/workspace/
└── logs/
    └── activity/
        ├── 2025-08-06.jsonl      # Daily log files
        ├── 2025-08-05.jsonl
        └── archive/              # Compressed old logs
            └── 2025-07.tar.gz

Log Retention Policy

Log Age Action Storage
0-7 days Active JSONL files
8-30 days Compressed Gzipped JSONL
31-90 days Archived Tar.gz monthly
>90 days Configurable Delete or long-term storage

Tool Execution Architecture

Handler Types and Implementation

Shell Script Handlers

#!/bin/bash
# tools/handlers/read-file.sh
FILE_PATH="$1"
if [ -f "$FILE_PATH" ]; then
    cat "$FILE_PATH"
else
    echo "Error: File not found" >&2
    exit 1
fi

Python Handlers

# tools/handlers/summarize.py
import sys
import json

def summarize_document(file_path, summary_length=5):
    with open(file_path, 'r') as f:
        content = f.read()
    # AI summarization logic here
    summary = generate_summary(content, summary_length)
    return json.dumps({"success": True, "summary": summary})

if __name__ == "__main__":
    result = summarize_document(sys.argv[1], int(sys.argv[2]))
    print(result)

JavaScript Handlers

// tools/handlers/create-excel.js
const xlsx = require('xlsx');

function createExcel(params) {
    const { data, filename, format } = JSON.parse(params);
    const workbook = xlsx.utils.book_new();
    const worksheet = xlsx.utils.json_to_sheet(data);
    xlsx.utils.book_append_sheet(workbook, worksheet, 'Sheet1');
    xlsx.writeFile(workbook, filename);
    return { success: true, file: filename };
}

const result = createExcel(process.argv[2]);
console.log(JSON.stringify(result));

Implementation Phases

Phase 1: Core Infrastructure with LLxprt (Week 1)

Tasks:

  1. Set up LLxprt integration in llxprt-bridge.js
  2. Create tool schema registry for JSON definitions
  3. Implement handler execution framework
  4. Set up activity logger service
  5. Create permission validation service
  6. Build tool discovery mechanism for schemas and handlers

Deliverables:

  • services/tool-executor.js - Orchestrates tool execution via LLxprt
  • services/tool-registry.js - Manages tool schemas and handlers
  • services/activity-logger.js - Logs all tool operations
  • services/tool-permission-service.js - Validates permissions
  • services/tool-discovery.js - Discovers available tools
  • tools/schemas/*.json - Tool definition schemas
  • tools/handlers/* - Tool implementation handlers

Phase 2: Tool Implementation (Week 2)

Tasks:

  1. Create JSON schemas for initial tools
  2. Implement handlers (shell/Python/JS)
  3. Write markdown documentation for each tool
  4. Set up confirmation workflows
  5. Add error handling and retry logic
  6. Create tool testing framework

Deliverables:

  • JSON schemas in /tools/schemas/
  • Handler scripts in /tools/handlers/
  • Documentation in /tools/docs/
  • Confirmation flow handlers
  • Error handling framework
  • Tool test suite

Phase 3: Integration (Week 3)

Tasks:

  1. Integrate with existing AI service
  2. Connect activity logging to all operations
  3. Implement WebSocket message handlers
  4. Add permission checks to execution flow
  5. Create audit trail system

Deliverables:

  • Updated sasha-ai-service.js
  • WebSocket protocol implementation
  • Audit trail functionality
  • Permission enforcement

Phase 4: User Interface (Week 4)

Tasks:

  1. Create admin settings interface
  2. Build activity log viewer
  3. Add tool selection UI
  4. Implement confirmation dialogs
  5. Create progress indicators

Deliverables:

  • Admin settings modal
  • Activity log dashboard
  • Tool selection interface
  • Confirmation UI components
  • Progress tracking displays

Phase 5: Testing & Refinement (Week 5)

Tasks:

  1. Unit tests for all services
  2. Integration testing
  3. Security testing
  4. Performance optimization
  5. Documentation completion

Deliverables:

  • Test suite
  • Performance benchmarks
  • Security audit report
  • Complete documentation

Success Criteria

Functional Requirements

  • Tools execute from markdown definitions
  • Natural language triggers work correctly
  • Permissions control tool availability
  • All operations logged to activity log
  • Confirmation flows work as designed

Performance Requirements

  • Tool discovery < 100ms
  • Tool execution < 5 seconds for simple operations
  • Activity log write < 10ms
  • Permission check < 5ms

Security Requirements

  • No path traversal vulnerabilities
  • All file operations sandboxed
  • Permissions cannot be bypassed
  • Activity log cannot be tampered with
  • Sensitive data redacted from logs

Security Considerations

Input Validation

  • Sanitize all user inputs
  • Validate file paths against whitelist
  • Check file sizes before operations
  • Verify command parameters

Permission Enforcement

  • Check permissions before execution
  • Validate user roles
  • Enforce rate limiting
  • Require confirmation for risky operations

Audit Trail

  • Log all operations
  • Include user identity
  • Track permission changes
  • Monitor failed attempts

Data Protection

  • Redact sensitive information from logs
  • Encrypt activity logs at rest
  • Implement log rotation
  • Secure backup procedures

Monitoring & Analytics

Key Metrics

  • Tool usage frequency
  • Success/failure rates
  • Average execution time
  • User engagement
  • Error patterns

Dashboards

  • Real-time activity monitor
  • Tool usage analytics
  • Error tracking dashboard
  • Performance metrics
  • User activity summary

Maintenance & Operations

Regular Tasks

  • Daily: Review activity logs for anomalies
  • Weekly: Check tool performance metrics
  • Monthly: Rotate and archive logs
  • Quarterly: Review and update permissions

Upgrade Path

  • Version control for tool definitions
  • Backward compatibility for logs
  • Migration scripts for schema changes
  • Rollback procedures

Documentation Requirements

For Developers

  • API documentation
  • Tool development guide
  • Integration examples
  • Troubleshooting guide

For Administrators

  • Permission management guide
  • Activity log analysis guide
  • Security best practices
  • Backup and recovery procedures

For Users

  • Tool usage guide
  • Available tools catalog
  • FAQ and common issues
  • Quick start tutorial

Benefits & Impact

For Users

  • Natural language tool invocation
  • No technical knowledge required
  • Consistent, high-quality outputs
  • Transparent operation tracking

For Administrators

  • Complete control over tool availability
  • Comprehensive audit trail
  • Risk-based permission management
  • Easy tool addition/modification

For Organization

  • Democratized tool access
  • Reduced training requirements
  • Improved compliance tracking
  • Enhanced productivity

Timeline

Week Phase Key Deliverables
1 Core Infrastructure Tool executor, Parser, Logger
2 Tool Definitions Initial tools, Templates
3 Integration AI service, WebSocket, Permissions
4 User Interface Admin UI, Log viewer, Tool UI
5 Testing Test suite, Security audit, Docs
6 Deployment Production release, Training

🚦 Next Steps

  1. Immediate Actions

    • Set up development environment
    • Create project structure
    • Initialize version control

  2. Week 1 Goals

    • Implement core services
    • Create first tool definition
    • Set up activity logging

  3. Success Milestones

    • First tool execution
    • Permission system working
    • Activity log capturing events
    • Admin UI functional

This comprehensive plan provides the complete blueprint for implementing Sasha's innovative tool system. The markdown-defined approach makes tools accessible to non-programmers while maintaining enterprise-grade security and auditability.