file-sender

# File Sender Packages workspace files into a ZIP, generates a companion description file, and notifies the Manager to deliver them to the user. Files are persisted locally to `.file-outbox/` first — even if notification fails, the files are safe. All required environment variables are injected automatically by the Manager at instance creation. No manual configuration needed. ## Core Workflow ### Step 1: Compose a Description Before running the script, write a concise description of what you generated. This description will be saved as a `.txt` file alongside the ZIP in `.file-outbox/`, serving as a human-readable summary for the user. The description should include: - What files/project were generated - The main purpose of the files - How to use them (brief instructions) **Good example:** ``` Snake game project (snake_game) Contains: index.html, style.css, game.js Usage: Open index.html in a browser to play the game ``` **Bad example:** ``` files ``` ### Step 2: Package and Send Pass the source path and the description text to the script: ```bash bash scripts/send-files.sh \ "/home/node/workspace/snake_game" \ "Snake game project with index.html, style.css, game.js. Open index.html in browser to play." ``` The script will: 1. **Validate the path** — Only allows files under `/home/node/workspace/`, blocks symlink traversal 2. **Create a ZIP** — Single file `zip`, directory `zip -r`, 500MB limit 3. **Write description** — Saves the description text as `{file_id}.txt` in `.file-outbox/` 4. **Persist locally** — Both ZIP and TXT are stored in `.file-outbox/` (safe on disk) 5. **Notify Manager** — Sends a lightweight POST with metadata only (no file body) 6. **Manager pulls** — Manager's background task pulls the ZIP from the Agent and forwards it > **Core design**: After step 4, files are safely on disk. Steps 5-6 failing does NOT lose the files. > The Manager retries automatically — the user will always receive the files eventually. ### Step 3: Confirm the Result The script outputs the result. Even if notification fails, the files are safely persisted locally. The system will retry delivery automatically. ## Quick Examples ```bash # Send a single file bash scripts/send-files.sh \ "/home/node/workspace/report.pdf" \ "Monthly sales report for March 2026, includes charts and summary tables." # Send an entire directory (auto-recursive ZIP) bash scripts/send-files.sh \ "/home/node/workspace/my_project" \ "Complete Python project with requirements.txt and README.md. Run: pip install -r requirements.txt && python main.py" ``` ### Sending Multiple Non-Adjacent Files Collect them into a temporary directory first: ```bash mkdir -p /tmp/delivery cp /home/node/workspace/report.pdf /tmp/delivery/ cp /home/node/workspace/data.csv /tmp/delivery/ bash scripts/send-files.sh "/tmp/delivery" "Analysis report + raw data CSV" ``` ## What Gets Saved in `.file-outbox/` For each delivery, two files are created: ``` .file-outbox/ ├── 20260401120000_a1b2c3d4.zip # The packaged files └── 20260401120000_a1b2c3d4.txt # The description text (human-readable) ``` The `.txt` file contains the exact description you provided, serving as a persistent record of what was sent and why. ## When to Trigger | Scenario | Trigger? | |----------|----------| | Created a complete project/application | ✅ Yes | | Generated documents/reports/data files | ✅ Yes | | User asks to "send files" | ✅ Yes | | Only explaining code / answering questions | ❌ No | | Modifying system config files | ❌ No | | Tiny single-line changes | ❌ No | ## Output Examples Success: ``` 📦 Packaging files... File ID: 20260401120000_a1b2c3d4 | Size: 156KB 📤 Notifying Manager... ✅ Notification sent! Files will be delivered to the user automatically. ``` Notification failure (files still safe): ``` ⚠️ Cannot connect to Manager. Files are safely stored locally. The system will retry automatically — the user will receive the files. ``` ## Limits | Limit | Value | |-------|-------| | Max file size | 500MB (after ZIP) | | Source path scope | `/home/node/workspace/` only | | Cannot send | `.file-outbox/` directory itself | ## Environment Requirements - `OPENCLAW_INSTANCE_NAME` — Instance name (auto-injected by Manager) - `OPENCLAW_MANAGER_URL` — File Push service URL (auto-injected by Manager) - `OPENCLAW_FILE_PUSH_TOKEN` — Instance-specific push token (auto-injected by Manager) - `curl` and `zip` commands must be available in PATH