pi-usereq 0.48.0 → 0.50.0

package/docs/pi.dev/mom-docs/sandbox.md

@@ -1,153 +0,0 @@
-# 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/pi.dev/mom-docs/slack-bot-minimal-guide.md

@@ -1,399 +0,0 @@
-# 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.