@oh-my-pi/pi-mom 0.1.0

package/docs/sandbox.md

@@ -0,0 +1,153 @@
+# Mom Docker Sandbox
+
+## Overview
+
+Mom can run tools either directly on the host or inside a Docker container for isolation.
+
+## Why Docker?
+
+When mom runs on your machine and is accessible via Slack, anyone in your workspace could potentially:
+- Execute arbitrary commands on your machine
+- Access your files, credentials, etc.
+- Cause damage via prompt injection
+
+The Docker sandbox isolates mom's tools to a container where she can only access what you explicitly mount.
+
+## Quick Start
+
+```bash
+# 1. Create and start the container
+cd packages/mom
+./docker.sh create ./data
+
+# 2. Run mom with Docker sandbox
+mom --sandbox=docker:mom-sandbox ./data
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Host                                               │
+│                                                     │
+│  mom process (Node.js)                              │
+│  ├── Slack connection                               │
+│  ├── LLM API calls                                  │
+│  └── Tool execution ──────┐                         │
+│                           ▼                         │
+│              ┌─────────────────────────┐            │
+│              │  Docker Container       │            │
+│              │  ├── bash, git, gh, etc │            │
+│              │  └── /workspace (mount) │            │
+│              └─────────────────────────┘            │
+└─────────────────────────────────────────────────────┘
+```
+
+- Mom process runs on host (handles Slack, LLM calls)
+- All tool execution (`bash`, `read`, `write`, `edit`) happens inside the container
+- Only `/workspace` (your data dir) is accessible to the container
+
+## Container Setup
+
+Use the provided script:
+
+```bash
+./docker.sh create <data-dir>   # Create and start container
+./docker.sh start               # Start existing container
+./docker.sh stop                # Stop container
+./docker.sh remove              # Remove container
+./docker.sh status              # Check if running
+./docker.sh shell               # Open shell in container
+```
+
+Or manually:
+
+```bash
+docker run -d --name mom-sandbox \
+  -v /path/to/mom-data:/workspace \
+  alpine:latest tail -f /dev/null
+```
+
+## Mom Manages Her Own Computer
+
+The container is treated as mom's personal computer. She can:
+
+- Install tools: `apk add github-cli git curl`
+- Configure credentials: `gh auth login`
+- Create files and directories
+- Persist state across restarts
+
+When mom needs a tool, she installs it. When she needs credentials, she asks you.
+
+### Example Flow
+
+```
+User: "@mom check the spine-runtimes repo"
+Mom:  "I need gh CLI. Installing..."
+      (runs: apk add github-cli)
+Mom:  "I need a GitHub token. Please provide one."
+User: "ghp_xxxx..."
+Mom:  (runs: echo "ghp_xxxx" | gh auth login --with-token)
+Mom:  "Done. Checking repo..."
+```
+
+## Persistence
+
+The container persists across:
+- `docker stop` / `docker start`
+- Host reboots
+
+Installed tools and configs remain until you `docker rm` the container.
+
+To start fresh: `./docker.sh remove && ./docker.sh create ./data`
+
+## CLI Options
+
+```bash
+# Run on host (default, no isolation)
+mom ./data
+
+# Run with Docker sandbox
+mom --sandbox=docker:mom-sandbox ./data
+
+# Explicit host mode
+mom --sandbox=host ./data
+```
+
+## Security Considerations
+
+**What the container CAN do:**
+- Read/write files in `/workspace` (your data dir)
+- Make network requests (for git, gh, curl, etc.)
+- Install packages
+- Run any commands
+
+**What the container CANNOT do:**
+- Access files outside `/workspace`
+- Access your host's credentials
+- Affect your host system
+
+**For maximum security:**
+1. Create a dedicated GitHub bot account with limited repo access
+2. Only share that bot's token with mom
+3. Don't mount sensitive directories
+
+## Troubleshooting
+
+### Container not running
+```bash
+./docker.sh status  # Check status
+./docker.sh start   # Start it
+```
+
+### Reset container
+```bash
+./docker.sh remove
+./docker.sh create ./data
+```
+
+### Missing tools
+Ask mom to install them, or manually:
+```bash
+docker exec mom-sandbox apk add <package>
+```

package/docs/slack-bot-minimal-guide.md

@@ -0,0 +1,399 @@
+# Minimal Slack Bot Setup (No Web Server, WebSocket Only)
+
+Here's how to connect your Node.js agent to Slack using **Socket Mode** - no Express, no HTTP server, just WebSockets and callbacks.
+
+---
+
+## 1. Dependencies
+
+```bash
+npm install @slack/socket-mode @slack/web-api
+```
+
+That's it. Two packages:
+- `@slack/socket-mode` - Receives events via WebSocket
+- `@slack/web-api` - Sends messages back to Slack
+
+---
+
+## 2. Get Your Tokens
+
+You need **TWO tokens**:
+
+### A. Bot Token (`xoxb-...`)
+1. Go to https://api.slack.com/apps
+2. Create app → "From scratch"
+3. Click "OAuth & Permissions" in sidebar
+4. Add **Bot Token Scopes** (all 16):
+   ```
+   app_mentions:read
+   channels:history
+   channels:join
+   channels:read
+   chat:write
+   files:read
+   files:write
+   groups:history
+   groups:read
+   im:history
+   im:read
+   im:write
+   mpim:history
+   mpim:read
+   mpim:write
+   users:read
+   ```
+5. Click "Install to Workspace" at top
+6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+
+### B. App-Level Token (`xapp-...`)
+1. In same app, click "Basic Information" in sidebar
+2. Scroll to "App-Level Tokens"
+3. Click "Generate Token and Scopes"
+4. Name it whatever (e.g., "socket-token")
+5. Add scope: `connections:write`
+6. Click "Generate"
+7. Copy the token (starts with `xapp-`)
+
+---
+
+## 3. Enable Socket Mode
+
+1. Go to https://api.slack.com/apps → select your app
+2. Click **"Socket Mode"** in sidebar
+3. Toggle **"Enable Socket Mode"** to ON
+4. This routes your app's interactions and events over WebSockets instead of public HTTP endpoints
+5. Done - no webhook URL needed!
+
+**Note:** Socket Mode is intended for internal apps in development or behind a firewall. Not for apps distributed via Slack Marketplace.
+
+---
+
+## 4. Enable Direct Messages
+
+1. Go to https://api.slack.com/apps → select your app
+2. Click **"App Home"** in sidebar
+3. Scroll to **"Show Tabs"** section
+4. Check **"Allow users to send Slash commands and messages from the messages tab"**
+5. Save
+
+---
+
+## 5. Subscribe to Events
+
+1. Go to https://api.slack.com/apps → select your app
+2. Click **"Event Subscriptions"** in sidebar
+3. Toggle **"Enable Events"** to ON
+4. **Important:** No Request URL needed (Socket Mode handles this)
+5. Expand **"Subscribe to bot events"**
+6. Click **"Add Bot User Event"** and add:
+   - `app_mention` (required - to see when bot is mentioned)
+   - `message.channels` (required - to log all channel messages for context)
+   - `message.groups` (optional - to see private channel messages)
+   - `message.im` (required - to see DMs)
+7. Click **"Save Changes"** at bottom
+
+---
+
+## 6. Store Tokens
+
+Create `.env` file:
+
+```bash
+SLACK_BOT_TOKEN=xoxb-your-bot-token-here
+SLACK_APP_TOKEN=xapp-your-app-token-here
+```
+
+Add to `.gitignore`:
+
+```bash
+echo ".env" >> .gitignore
+```
+
+---
+
+## 7. Minimal Working Code
+
+```javascript
+require('dotenv').config();
+const { SocketModeClient } = require('@slack/socket-mode');
+const { WebClient } = require('@slack/web-api');
+
+const socketClient = new SocketModeClient({ 
+  appToken: process.env.SLACK_APP_TOKEN 
+});
+
+const webClient = new WebClient(process.env.SLACK_BOT_TOKEN);
+
+// Listen for app mentions (@mom do something)
+socketClient.on('app_mention', async ({ event, ack }) => {
+  try {
+    // Acknowledge receipt
+    await ack();
+    
+    console.log('Mentioned:', event.text);
+    console.log('Channel:', event.channel);
+    console.log('User:', event.user);
+    
+    // Process with your agent
+    const response = await yourAgentFunction(event.text);
+    
+    // Send response
+    await webClient.chat.postMessage({
+      channel: event.channel,
+      text: response
+    });
+  } catch (error) {
+    console.error('Error:', error);
+  }
+});
+
+// Start the connection
+(async () => {
+  await socketClient.start();
+  console.log('⚡️ Bot connected and listening!');
+})();
+
+// Your existing agent logic
+async function yourAgentFunction(text) {
+  // Your code here
+  return "I processed: " + text;
+}
+```
+
+**That's it. No web server. Just run it:**
+
+```bash
+node bot.js
+```
+
+---
+
+## 8. Listen to ALL Events (Not Just Mentions)
+
+If you want to see every message in channels/DMs the bot is in:
+
+```javascript
+// Listen to all Slack events
+socketClient.on('slack_event', async ({ event, body, ack }) => {
+  await ack();
+  
+  console.log('Event type:', event.type);
+  console.log('Event data:', event);
+  
+  if (event.type === 'message' && event.subtype === undefined) {
+    // Regular message (not bot message, not edited, etc.)
+    console.log('Message:', event.text);
+    console.log('Channel:', event.channel);
+    console.log('User:', event.user);
+    
+    // Your logic here
+  }
+});
+```
+
+---
+
+## 9. Common Operations
+
+### Send a message
+```javascript
+await webClient.chat.postMessage({
+  channel: 'C12345', // or channel ID from event
+  text: 'Hello!'
+});
+```
+
+### Send a DM
+```javascript
+// Open DM channel with user
+const result = await webClient.conversations.open({
+  users: 'U12345' // user ID
+});
+
+// Send message to that DM
+await webClient.chat.postMessage({
+  channel: result.channel.id,
+  text: 'Hey there!'
+});
+```
+
+### List channels
+```javascript
+const channels = await webClient.conversations.list({
+  types: 'public_channel,private_channel'
+});
+console.log(channels.channels);
+```
+
+### Get channel members
+```javascript
+const members = await webClient.conversations.members({
+  channel: 'C12345'
+});
+console.log(members.members); // Array of user IDs
+```
+
+### Get user info
+```javascript
+const user = await webClient.users.info({
+  user: 'U12345'
+});
+console.log(user.user.name);
+console.log(user.user.real_name);
+```
+
+### Join a channel
+```javascript
+await webClient.conversations.join({
+  channel: 'C12345'
+});
+```
+
+### Upload a file
+```javascript
+await webClient.files.uploadV2({
+  channel_id: 'C12345',
+  file: fs.createReadStream('./file.pdf'),
+  filename: 'document.pdf',
+  title: 'My Document'
+});
+```
+
+---
+
+## 10. Complete Example with Your Agent
+
+```javascript
+require('dotenv').config();
+const { SocketModeClient } = require('@slack/socket-mode');
+const { WebClient } = require('@slack/web-api');
+
+const socketClient = new SocketModeClient({ 
+  appToken: process.env.SLACK_APP_TOKEN 
+});
+
+const webClient = new WebClient(process.env.SLACK_BOT_TOKEN);
+
+// Your existing agent/AI/whatever
+class MyAgent {
+  async process(message, context) {
+    // Your complex logic here
+    // context has: user, channel, etc.
+    return `Processed: ${message}`;
+  }
+}
+
+const agent = new MyAgent();
+
+// Handle mentions
+socketClient.on('app_mention', async ({ event, ack }) => {
+  await ack();
+  
+  try {
+    // Remove the @mention from text
+    const text = event.text.replace(/<@[A-Z0-9]+>/g, '').trim();
+    
+    // Process with your agent
+    const response = await agent.process(text, {
+      user: event.user,
+      channel: event.channel
+    });
+    
+    // Send response
+    await webClient.chat.postMessage({
+      channel: event.channel,
+      text: response
+    });
+  } catch (error) {
+    console.error('Error processing mention:', error);
+    
+    // Send error message
+    await webClient.chat.postMessage({
+      channel: event.channel,
+      text: 'Sorry, something went wrong!'
+    });
+  }
+});
+
+// Start
+(async () => {
+  await socketClient.start();
+  console.log('⚡️ Agent connected to Slack!');
+})();
+```
+
+---
+
+## 11. Available Event Types
+
+You subscribed to these in step 4:
+
+- `app_mention` - Someone @mentioned the bot
+- `message` - Any message in a channel/DM the bot is in
+
+Event object structure:
+
+```javascript
+{
+  type: 'app_mention' or 'message',
+  text: 'the message text',
+  user: 'U12345', // who sent it
+  channel: 'C12345', // where it was sent
+  ts: '1234567890.123456' // timestamp
+}
+```
+
+---
+
+## 12. Advantages of Socket Mode
+
+✅ **No web server needed** - just run your script  
+✅ **No public URL needed** - works behind firewall  
+✅ **No ngrok** - works on localhost  
+✅ **Auto-reconnect** - SDK handles connection drops  
+✅ **Event-driven** - just listen to callbacks  
+
+---
+
+## 13. Disadvantages
+
+❌ Can't distribute to Slack App Directory (only for your workspace)  
+❌ Script must be running to receive messages (unlike webhooks)  
+❌ Max 10 concurrent connections per app  
+
+---
+
+## Important Notes
+
+1. **You MUST call `ack()`** on every event or Slack will retry
+2. **Bot token** (`xoxb-`) is for sending messages
+3. **App token** (`xapp-`) is for receiving events via WebSocket
+4. **Connection is persistent** - your script stays running
+5. **No URL validation** needed (unlike HTTP webhooks)
+
+---
+
+## Troubleshooting
+
+### "invalid_auth" error
+- Check you're using the right tokens
+- Bot token for WebClient, App token for SocketModeClient
+
+### "missing_scope" error
+- Make sure you added all 16 bot scopes
+- Reinstall the app after adding scopes
+
+### Not receiving events
+- Check Socket Mode is enabled
+- Check you subscribed to events in "Event Subscriptions"
+- Make sure bot is in the channel (or use `channels:join`)
+
+### Bot doesn't respond to mentions
+- Must subscribe to `app_mention` event
+- Bot must be installed to workspace
+- Check `await ack()` is called
+
+---
+
+That's it. No HTTP server bullshit. Just WebSockets and callbacks.