clodds 1.2.9 → 1.4.0

package/dist/skills/bundled/presence/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: presence
+description: "Online status, activity tracking, and multi-device sync"
+emoji: "🟢"
+---
+
+# Presence - Complete API Reference
+
+Manage online status, track activity across devices, and sync presence information.
+
+---
+
+## Chat Commands
+
+### View Status
+
+```
+/presence                                   Show your status
+/presence who                               Who's online
+/presence activity                          Recent activity
+```
+
+### Set Status
+
+```
+/presence online                            Set online
+/presence away                              Set away
+/presence dnd                               Do not disturb
+/presence offline                           Appear offline
+/presence status "In a meeting"             Custom status
+```
+
+### Devices
+
+```
+/presence devices                           Your connected devices
+/presence sync                              Force sync all devices
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Presence Service
+
+```typescript
+import { createPresenceService } from 'clodds/presence';
+
+const presence = createPresenceService({
+  // Update interval
+  heartbeatIntervalMs: 30000,
+
+  // Auto-away after idle
+  awayAfterMs: 300000,  // 5 minutes
+
+  // Storage
+  storage: 'redis',  // 'redis' | 'memory'
+  redisUrl: process.env.REDIS_URL,
+});
+```
+
+### Get Status
+
+```typescript
+// Get own status
+const status = await presence.getStatus(userId);
+
+console.log(`Status: ${status.status}`);  // 'online' | 'away' | 'dnd' | 'offline'
+console.log(`Custom: ${status.customStatus}`);
+console.log(`Last seen: ${status.lastSeen}`);
+console.log(`Device: ${status.activeDevice}`);
+
+// Get multiple users
+const statuses = await presence.getStatuses(['user-1', 'user-2', 'user-3']);
+```
+
+### Set Status
+
+```typescript
+// Set status
+await presence.setStatus(userId, 'online');
+await presence.setStatus(userId, 'away');
+await presence.setStatus(userId, 'dnd');
+await presence.setStatus(userId, 'offline');
+
+// Set custom status message
+await presence.setCustomStatus(userId, 'Trading BTC');
+
+// Clear custom status
+await presence.clearCustomStatus(userId);
+```
+
+### Activity Tracking
+
+```typescript
+// Record activity
+await presence.recordActivity(userId, {
+  type: 'message',
+  channelId: 'telegram-123',
+  timestamp: Date.now(),
+});
+
+// Get recent activity
+const activity = await presence.getActivity(userId, {
+  limit: 10,
+  since: Date.now() - 3600000,  // Last hour
+});
+
+for (const event of activity) {
+  console.log(`${event.type} at ${event.timestamp}`);
+  console.log(`  Channel: ${event.channelId}`);
+}
+```
+
+### Device Presence
+
+```typescript
+// Get user's devices
+const devices = await presence.getDevices(userId);
+
+for (const device of devices) {
+  console.log(`${device.id}: ${device.name}`);
+  console.log(`  Status: ${device.status}`);
+  console.log(`  Last seen: ${device.lastSeen}`);
+  console.log(`  Active: ${device.isActive}`);
+}
+
+// Set device status
+await presence.setDeviceStatus(userId, deviceId, 'online');
+```
+
+### Who's Online
+
+```typescript
+// Get online users
+const online = await presence.getOnlineUsers({
+  channelId: 'telegram-123',  // Optional: filter by channel
+});
+
+for (const user of online) {
+  console.log(`${user.name}: ${user.status}`);
+}
+```
+
+### Event Handlers
+
+```typescript
+// Status changes
+presence.on('statusChange', (userId, oldStatus, newStatus) => {
+  console.log(`${userId}: ${oldStatus} -> ${newStatus}`);
+});
+
+// User came online
+presence.on('online', (userId) => {
+  console.log(`${userId} is now online`);
+});
+
+// User went offline
+presence.on('offline', (userId) => {
+  console.log(`${userId} went offline`);
+});
+```
+
+### Sync Across Devices
+
+```typescript
+// Force sync
+await presence.sync(userId);
+
+// Get sync status
+const syncStatus = await presence.getSyncStatus(userId);
+console.log(`Devices synced: ${syncStatus.synced}/${syncStatus.total}`);
+console.log(`Last sync: ${syncStatus.lastSync}`);
+```
+
+---
+
+## Status Types
+
+| Status | Description |
+|--------|-------------|
+| `online` | Active and available |
+| `away` | Idle/inactive |
+| `dnd` | Do not disturb |
+| `offline` | Not available |
+
+---
+
+## Auto-Away
+
+Presence automatically changes to `away` after inactivity:
+
+```typescript
+const presence = createPresenceService({
+  awayAfterMs: 300000,    // 5 min idle -> away
+  offlineAfterMs: 3600000, // 1 hour idle -> offline
+});
+```
+
+---
+
+## Multi-Device Sync
+
+When user is active on multiple devices:
+- Most recent activity determines primary device
+- Status syncs across all devices
+- Custom status shared everywhere
+
+---
+
+## Best Practices
+
+1. **Use heartbeats** — Keep status accurate
+2. **Set away appropriately** — Don't spam status changes
+3. **Custom status** — Let others know what you're doing
+4. **Review devices** — Keep device list clean
+5. **DND for focus** — Mute notifications during trades

package/dist/skills/bundled/presence/index.js

@@ -128,8 +128,8 @@ async function execute(args) {
                 return helpText();
         }
     }
-    catch {
-        return helpText();
+    catch (error) {
+        return `Error: ${error instanceof Error ? error.message : String(error)}`;
     }
 }
 function helpText() {

package/dist/skills/bundled/presence/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/skills/bundled/presence/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/skills/bundled/presence/index.ts"],"names":[],"mappings":"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"}

package/dist/skills/bundled/processes/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: processes
+description: "Background jobs, long-running processes, and task management"
+emoji: "⚙️"
+---
+
+# Processes - Complete API Reference
+
+Spawn and manage background processes, long-running jobs, and scheduled tasks.
+
+---
+
+## Chat Commands
+
+### Spawn Jobs
+
+```
+/job spawn "npm run backtest"               Start background job
+/job spawn "python train.py" --name ml      Named job
+/job spawn "node bot.js" --restart          Auto-restart on exit
+```
+
+### Manage Jobs
+
+```
+/jobs                                       List all jobs
+/job status <id>                            Check job status
+/job output <id>                            View job output
+/job output <id> --follow                   Stream output
+/job stop <id>                              Stop job
+/job restart <id>                           Restart job
+```
+
+### Logs
+
+```
+/job logs <id>                              View logs
+/job logs <id> --tail 100                   Last 100 lines
+/job logs <id> --since 1h                   Last hour
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Process Manager
+
+```typescript
+import { createProcessManager } from 'clodds/processes';
+
+const processes = createProcessManager({
+  // Working directory
+  cwd: process.cwd(),
+
+  // Environment
+  env: process.env,
+
+  // Limits
+  maxProcesses: 10,
+  maxMemoryMB: 1024,
+
+  // Logging
+  logDir: './logs/jobs',
+  maxLogSizeMB: 100,
+
+  // Storage
+  storage: 'sqlite',
+  dbPath: './jobs.db',
+});
+```
+
+### Spawn Process
+
+```typescript
+// Simple spawn
+const job = await processes.spawn({
+  command: 'npm',
+  args: ['run', 'backtest'],
+  name: 'backtest-btc',
+});
+
+console.log(`Job ID: ${job.id}`);
+console.log(`PID: ${job.pid}`);
+
+// With options
+const job = await processes.spawn({
+  command: 'python',
+  args: ['train.py', '--epochs', '100'],
+  name: 'ml-training',
+
+  // Environment
+  env: {
+    ...process.env,
+    CUDA_VISIBLE_DEVICES: '0',
+  },
+
+  // Working directory
+  cwd: '/path/to/ml-project',
+
+  // Auto-restart
+  restart: true,
+  maxRestarts: 3,
+  restartDelayMs: 5000,
+
+  // Resource limits
+  maxMemoryMB: 4096,
+  timeoutMs: 3600000,  // 1 hour
+});
+```
+
+### List Jobs
+
+```typescript
+const jobs = await processes.list();
+
+for (const job of jobs) {
+  console.log(`${job.id}: ${job.name}`);
+  console.log(`  Status: ${job.status}`);  // 'running' | 'stopped' | 'failed' | 'completed'
+  console.log(`  PID: ${job.pid}`);
+  console.log(`  Started: ${job.startedAt}`);
+  console.log(`  Memory: ${job.memoryMB}MB`);
+  console.log(`  CPU: ${job.cpuPercent}%`);
+}
+```
+
+### Get Status
+
+```typescript
+const status = await processes.getStatus(jobId);
+
+console.log(`Status: ${status.status}`);
+console.log(`Exit code: ${status.exitCode}`);
+console.log(`Runtime: ${status.runtimeMs}ms`);
+console.log(`Restarts: ${status.restarts}`);
+console.log(`Memory: ${status.memoryMB}MB`);
+console.log(`CPU: ${status.cpuPercent}%`);
+```
+
+### Get Output
+
+```typescript
+// Get all output
+const output = await processes.getOutput(jobId);
+console.log(output.stdout);
+console.log(output.stderr);
+
+// Get last N lines
+const output = await processes.getOutput(jobId, { tail: 100 });
+
+// Stream output
+const stream = processes.streamOutput(jobId);
+stream.on('stdout', (data) => console.log(data));
+stream.on('stderr', (data) => console.error(data));
+stream.on('exit', (code) => console.log(`Exit: ${code}`));
+```
+
+### Stop Job
+
+```typescript
+// Graceful stop (SIGTERM)
+await processes.stop(jobId);
+
+// Force kill (SIGKILL)
+await processes.stop(jobId, { force: true });
+
+// Stop all
+await processes.stopAll();
+```
+
+### Restart Job
+
+```typescript
+await processes.restart(jobId);
+```
+
+### Event Handlers
+
+```typescript
+processes.on('started', (job) => {
+  console.log(`Job started: ${job.name}`);
+});
+
+processes.on('stopped', (job) => {
+  console.log(`Job stopped: ${job.name} (code: ${job.exitCode})`);
+});
+
+processes.on('failed', (job, error) => {
+  console.error(`Job failed: ${job.name}`, error);
+});
+
+processes.on('output', (job, type, data) => {
+  console.log(`[${job.name}] ${type}: ${data}`);
+});
+```
+
+---
+
+## Job Status
+
+| Status | Description |
+|--------|-------------|
+| `running` | Currently executing |
+| `stopped` | Stopped by user |
+| `completed` | Finished successfully |
+| `failed` | Exited with error |
+| `restarting` | Auto-restarting |
+
+---
+
+## Use Cases
+
+### Run Backtest
+
+```typescript
+const job = await processes.spawn({
+  command: 'npm',
+  args: ['run', 'backtest', '--', '--strategy', 'momentum'],
+  name: 'backtest-momentum',
+});
+
+// Wait for completion
+const result = await processes.wait(job.id);
+console.log(`Backtest complete: ${result.exitCode === 0 ? 'success' : 'failed'}`);
+```
+
+### Train ML Model
+
+```typescript
+const job = await processes.spawn({
+  command: 'python',
+  args: ['train.py'],
+  name: 'ml-training',
+  cwd: './ml',
+  maxMemoryMB: 8192,
+  timeoutMs: 86400000,  // 24 hours
+});
+
+// Monitor progress
+processes.streamOutput(job.id).on('stdout', (line) => {
+  if (line.includes('Epoch')) {
+    console.log(line);
+  }
+});
+```
+
+---
+
+## Best Practices
+
+1. **Name your jobs** — Easier to identify
+2. **Set timeouts** — Prevent runaway processes
+3. **Monitor memory** — Prevent OOM kills
+4. **Use restart sparingly** — Debug failures first
+5. **Check logs** — Always review output