2ndbrain 2026.1.30 → 2026.1.31

package/skills/system-ops/SKILL.md

@@ -0,0 +1,161 @@
+# Skill: system-ops
+
+## Description
+
+Check system health, uptime, memory usage, disk space, and database status. This skill provides **read-only** system diagnostics. It answers questions about how the system is running, surfaces recent errors, and reports resource usage.
+
+## READ-ONLY RESTRICTION
+
+**THIS SKILL IS STRICTLY READ-ONLY.** You must NEVER use this skill to:
+
+- Restart, reboot, or shut down the system or any service
+- Kill or stop any process
+- Modify any system configuration
+- Delete any files or data
+- Run any command that changes system state
+
+Restart, reboot, and shutdown operations are handled exclusively by slash commands (`/restart`, `/reboot`, `/stop`) with confirmation prompts. If the user asks you to restart or reboot through conversation, direct them to use the appropriate slash command instead.
+
+## When to Activate
+
+Activate this skill automatically when the user asks about system health or status. Common triggers include:
+
+- "How's the system?" or "Is everything running?"
+- "Check disk space" or "How much storage is left?"
+- "Memory usage" or "How much RAM is being used?"
+- "System uptime" or "How long has the system been running?"
+- "Are there any errors?" or "Check for recent problems"
+- "Database status" or "Is the database OK?"
+- "System health" or "Give me a health check"
+
+## Available Tools
+
+- **Bash** -- Execute read-only shell commands. Only the following commands are permitted:
+  - `uptime` -- System uptime
+  - `free -h` -- Memory usage
+  - `df -h` -- Disk usage
+  - `pg_isready` -- PostgreSQL connection check
+
+- **`mcp__pg__query`** -- Execute read-only SQL queries against the PostgreSQL database.
+
+No other tools are permitted for this skill.
+
+## Database Tables (Read-Only Access)
+
+### `system_logs`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of the log entry |
+| `level` | TEXT | Log level: `'debug'`, `'info'`, `'warn'`, `'error'` |
+| `source` | TEXT | Component name (e.g., `'telegram'`, `'claude'`, `'process'`) |
+| `content` | TEXT | Log message content |
+
+### `conversation_messages` (Read-Only Access)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL PRIMARY KEY | Auto-incrementing identifier |
+| `created_at` | TIMESTAMPTZ | Timestamp of the message |
+| `session_id` | TEXT | Claude CLI session ID |
+| `role` | TEXT | Message role: `'user'`, `'assistant'`, `'system'`, `'summary'` |
+| `content` | TEXT | Message content |
+
+## Operations
+
+### System Uptime
+
+Report how long the system has been running.
+
+```bash
+uptime
+```
+
+Present the output in a human-readable way (e.g., "The system has been running for 3 days, 4 hours").
+
+### Memory Usage
+
+Check current RAM usage.
+
+```bash
+free -h
+```
+
+Summarize the key figures: total memory, used memory, available memory. Flag if available memory is critically low (under 10% of total).
+
+### Disk Usage
+
+Check available disk space.
+
+```bash
+df -h
+```
+
+Focus on the root filesystem and any mounted data partitions. Flag if any partition is above 90% usage.
+
+### Database Status
+
+Check whether PostgreSQL is accepting connections.
+
+```bash
+pg_isready
+```
+
+Also check the conversation message count as a basic activity indicator:
+
+```sql
+SELECT COUNT(*) AS total_messages FROM conversation_messages;
+```
+
+And check the most recent conversation activity:
+
+```sql
+SELECT created_at AS last_activity
+FROM conversation_messages
+ORDER BY created_at DESC
+LIMIT 1;
+```
+
+### Recent Errors
+
+Retrieve the most recent error log entries.
+
+```sql
+SELECT created_at, source, content
+FROM system_logs
+WHERE level = 'error'
+ORDER BY created_at DESC
+LIMIT 5;
+```
+
+If no errors are found, report that clearly: "No recent errors found."
+
+For a broader view including warnings:
+
+```sql
+SELECT created_at, level, source, content
+FROM system_logs
+WHERE level IN ('error', 'warn')
+ORDER BY created_at DESC
+LIMIT 10;
+```
+
+### Full Health Summary
+
+When the user asks for a general health check, run all of the above operations and present a consolidated summary covering:
+
+1. System uptime
+2. Memory usage (total / used / available)
+3. Disk usage (used / available / percent)
+4. Database status (connected / message count / last activity)
+5. Recent errors (count and brief summary, or "none")
+
+## Restrictions and Notes
+
+- **READ-ONLY ONLY.** Never run commands that modify system state. No `sudo`, no `kill`, no `systemctl restart`, no `rm`, no writes of any kind.
+- Only use the four whitelisted Bash commands: `uptime`, `free -h`, `df -h`, `pg_isready`. Do not execute any other shell commands through this skill.
+- Only run SELECT queries against the database. Never INSERT, UPDATE, DELETE, or DROP.
+- If the user asks to restart, reboot, or shut down the system, respond: "I can only check system status. To restart or reboot, please use the `/restart` or `/reboot` slash commands."
+- Present diagnostic information in a clear, summarized format. Avoid dumping raw command output -- interpret it for the user.
+- If any check fails (e.g., `pg_isready` returns an error), report the failure clearly and suggest next steps (e.g., "The database appears to be down. You may want to check the PostgreSQL service.").

package/src/attachments/store.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/**
+ * Map of common MIME types to file extensions.
+ * Falls back to the MIME subtype or "bin" for unknown types.
+ */
+const MIME_TO_EXT = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/bmp': 'bmp',
+  'image/svg+xml': 'svg',
+  'image/tiff': 'tiff',
+  'video/mp4': 'mp4',
+  'video/webm': 'webm',
+  'video/quicktime': 'mov',
+  'audio/ogg': 'ogg',
+  'audio/mpeg': 'mp3',
+  'audio/mp4': 'm4a',
+  'audio/wav': 'wav',
+  'audio/x-wav': 'wav',
+  'application/pdf': 'pdf',
+  'application/zip': 'zip',
+  'application/gzip': 'gz',
+  'application/x-tar': 'tar',
+  'text/plain': 'txt',
+  'text/html': 'html',
+  'text/csv': 'csv',
+  'application/json': 'json',
+  'application/xml': 'xml',
+  'application/octet-stream': 'bin',
+};
+
+/**
+ * Derive a file extension from a MIME type string.
+ *
+ * @param {string|undefined} mimeType
+ * @returns {string} File extension without leading dot.
+ */
+function extFromMime(mimeType) {
+  if (!mimeType) return 'bin';
+  return MIME_TO_EXT[mimeType] || mimeType.split('/').pop() || 'bin';
+}
+
+/**
+ * Attachment store -- downloads Telegram file attachments, saves them to
+ * a date-organized directory tree under $DATA_DIR/attachments/, and records
+ * metadata in the attachments database table (spec section 8).
+ */
+class AttachmentStore {
+  /**
+   * @param {object} deps
+   * @param {object} deps.db     - Database query interface ({ query(sql, params) }).
+   * @param {object} deps.bot    - Telegram bot adapter ({ downloadFile(fileId): Promise<Buffer> }).
+   * @param {object} deps.config - Application configuration (needs DATA_DIR).
+   * @param {object} deps.logger - Logger instance.
+   */
+  constructor({ db, bot, config, logger }) {
+    this.db = db;
+    this.bot = bot;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  /**
+   * Download a Telegram attachment, persist it to disk, and insert a
+   * database record.
+   *
+   * Storage path: $DATA_DIR/attachments/YYYY/MM/DD/{uuid}.{ext}
+   *
+   * @param {object} attachment - Telegram attachment metadata.
+   * @param {string} attachment.file_id       - Telegram file identifier.
+   * @param {string} [attachment.mime_type]    - MIME type of the file.
+   * @param {number} [attachment.file_size]    - File size in bytes.
+   * @param {number} messageId - ID of the parent conversation_messages row.
+   * @returns {Promise<{ id: number, filePath: string, mimeType: string|null, fileSize: number }>}
+   */
+  async save(attachment, messageId) {
+    const { file_id: fileId, mime_type: mimeType, file_size: fileSize } = attachment;
+
+    // 1. Download the file from Telegram
+    const fileBuffer = await this.bot.downloadFile(fileId);
+
+    // 2. Build the date-organized storage path
+    const now = new Date();
+    const year = String(now.getFullYear());
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+
+    const ext = extFromMime(mimeType);
+    const filename = `${crypto.randomUUID()}.${ext}`;
+
+    const relativeDir = path.join('attachments', year, month, day);
+    const absoluteDir = path.join(this.config.DATA_DIR, relativeDir);
+    const relativePath = path.join(relativeDir, filename);
+    const absolutePath = path.join(absoluteDir, filename);
+
+    // 3. Create directory structure if needed
+    fs.mkdirSync(absoluteDir, { recursive: true });
+
+    // 4. Save the file to disk
+    fs.writeFileSync(absolutePath, fileBuffer);
+
+    const actualSize = fileSize ?? fileBuffer.length;
+
+    // 5. Insert record into the attachments table
+    const result = await this.db.query(
+      `INSERT INTO attachments (message_id, telegram_file_id, mime_type, file_path, file_size)
+       VALUES ($1, $2, $3, $4, $5)
+       RETURNING id`,
+      [messageId, fileId, mimeType || null, relativePath, actualSize],
+    );
+
+    const record = {
+      id: result.rows[0].id,
+      filePath: relativePath,
+      mimeType: mimeType || null,
+      fileSize: actualSize,
+    };
+
+    this.logger.info(
+      'attachments',
+      `Saved attachment ${record.id}: ${relativePath} (${actualSize} bytes)`,
+    );
+
+    // 6. Return the attachment record
+    return record;
+  }
+
+  /**
+   * Retrieve all attachment records associated with a conversation message.
+   *
+   * @param {number} messageId - ID of the conversation_messages row.
+   * @returns {Promise<Array<{
+   *   id: number,
+   *   filePath: string,
+   *   mimeType: string|null,
+   *   fileSize: number,
+   *   telegramFileId: string|null,
+   *   createdAt: Date
+   * }>>}
+   */
+  async getByMessageId(messageId) {
+    const result = await this.db.query(
+      `SELECT id, file_path, mime_type, file_size, telegram_file_id, created_at
+       FROM attachments
+       WHERE message_id = $1
+       ORDER BY created_at ASC`,
+      [messageId],
+    );
+
+    return result.rows.map((row) => ({
+      id: row.id,
+      filePath: row.file_path,
+      mimeType: row.mime_type,
+      fileSize: row.file_size,
+      telegramFileId: row.telegram_file_id,
+      createdAt: row.created_at,
+    }));
+  }
+}
+
+export { AttachmentStore };
+export default AttachmentStore;

package/src/claude/bridge.js

@@ -0,0 +1,291 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Claude CLI subprocess bridge (spec section 5).
+ *
+ * Spawns `claude -p` as a child process for each conversational message.
+ * Emits 'typing' events during streaming (for refreshing Telegram typing
+ * indicator) and 'error' events on failures.
+ */
+class ClaudeBridge extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {object} options.config - Application configuration object
+   * @param {object} options.logger - Structured logger instance
+   * @param {object} [options.hooks] - Optional lifecycle hooks
+   */
+  constructor({ config, logger, hooks = {} }) {
+    super();
+    this.config = config;
+    this.logger = logger;
+    this.hooks = hooks;
+
+    /** @type {import('node:child_process').ChildProcess | null} */
+    this.activeProcess = null;
+  }
+
+  /**
+   * Invoke the Claude CLI with a user message.
+   *
+   * For new sessions (no sessionId), spawns with full configuration flags.
+   * For continuations, spawns with --resume to continue the existing session.
+   * The user message is piped via stdin to handle special characters safely.
+   *
+   * @param {string} message - The user message to send
+   * @param {string|null} [sessionId=null] - Existing session ID for continuation
+   * @param {string} [systemPrompt=''] - System prompt for new sessions
+   * @returns {Promise<{ text: string, sessionId: string, cost: number, duration: number, toolCalls: Array }>}
+   */
+  async invoke(message, sessionId = null, systemPrompt = '') {
+    const startTime = Date.now();
+    const args = this._buildArgs(sessionId, systemPrompt);
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn('claude', args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      this.activeProcess = proc;
+
+      let stdoutBuffer = '';
+      let stderrBuffer = '';
+      const textChunks = [];
+      const toolCalls = [];
+      let resultData = null;
+      let timedOut = false;
+
+      // Set up the timeout guard
+      const timeout = setTimeout(() => {
+        timedOut = true;
+        this.logger.warn('claude', `Subprocess timed out after ${this.config.CLAUDE_TIMEOUT}ms`);
+        this.kill();
+      }, this.config.CLAUDE_TIMEOUT);
+
+      // Pipe the user message via stdin and close it
+      proc.stdin.write(message);
+      proc.stdin.end();
+
+      // Collect and parse stdout stream-json chunks
+      proc.stdout.on('data', (chunk) => {
+        stdoutBuffer += chunk.toString();
+
+        // Process complete lines (NDJSON: one JSON object per line)
+        const lines = stdoutBuffer.split('\n');
+        // Keep the last potentially incomplete line in the buffer
+        stdoutBuffer = lines.pop() || '';
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+
+          try {
+            const parsed = JSON.parse(trimmed);
+            this._handleStreamChunk(parsed, textChunks, toolCalls);
+
+            if (parsed.type === 'result') {
+              resultData = parsed;
+            }
+          } catch {
+            // Non-JSON line; ignore
+            this.logger.debug('claude', `Non-JSON stdout line: ${trimmed}`);
+          }
+        }
+      });
+
+      // Monitor stderr for errors
+      proc.stderr.on('data', (chunk) => {
+        stderrBuffer += chunk.toString();
+      });
+
+      proc.on('close', (code) => {
+        clearTimeout(timeout);
+        this.activeProcess = null;
+
+        // Process any remaining data in the stdout buffer
+        if (stdoutBuffer.trim()) {
+          try {
+            const parsed = JSON.parse(stdoutBuffer.trim());
+            this._handleStreamChunk(parsed, textChunks, toolCalls);
+            if (parsed.type === 'result') {
+              resultData = parsed;
+            }
+          } catch {
+            // Ignore trailing non-JSON data
+          }
+        }
+
+        const duration = Date.now() - startTime;
+
+        if (timedOut) {
+          reject(new Error(`Claude subprocess timed out after ${this.config.CLAUDE_TIMEOUT}ms`));
+          return;
+        }
+
+        if (code !== 0 && !resultData) {
+          const errMsg = stderrBuffer.trim() || `Claude process exited with code ${code}`;
+          this.logger.error('claude', errMsg);
+          this.emit('error', new Error(errMsg));
+          reject(new Error(errMsg));
+          return;
+        }
+
+        if (stderrBuffer.trim()) {
+          this.logger.debug('claude', `stderr: ${stderrBuffer.trim()}`);
+        }
+
+        const text = textChunks.join('');
+        const resolvedSessionId = resultData?.session_id || sessionId || '';
+        const cost = resultData?.total_cost_usd ?? 0;
+
+        this.logger.info(
+          'claude',
+          `Response received (session=${resolvedSessionId}, cost=$${cost.toFixed(4)}, duration=${duration}ms)`,
+        );
+
+        resolve({
+          text,
+          sessionId: resolvedSessionId,
+          cost,
+          duration,
+          toolCalls,
+        });
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timeout);
+        this.activeProcess = null;
+        this.logger.error('claude', `Failed to spawn claude: ${err.message}`);
+        this.emit('error', err);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Build the CLI argument array for the claude subprocess.
+   *
+   * @param {string|null} sessionId - Session ID for continuation, or null for new
+   * @param {string} systemPrompt - System prompt for new sessions
+   * @returns {string[]}
+   * @private
+   */
+  _buildArgs(sessionId, systemPrompt) {
+    const args = ['-p', '--output-format', 'stream-json', '--verbose'];
+
+    if (sessionId) {
+      // Continuation: resume an existing session
+      args.push('--resume', sessionId);
+    } else {
+      // New session: full configuration
+      args.push('--model', this.config.CLAUDE_MODEL);
+
+      if (systemPrompt) {
+        args.push('--system-prompt', systemPrompt);
+      }
+
+      args.push('--mcp-config', this.config.MCP_CONFIG_PATH);
+      args.push('--allowed-tools', this.config.MCP_TOOLS_WHITELIST);
+
+      if (this.config.CLAUDE_MAX_BUDGET) {
+        args.push('--max-budget-usd', this.config.CLAUDE_MAX_BUDGET);
+      }
+    }
+
+    return args;
+  }
+
+  /**
+   * Handle a single parsed stream-json chunk.
+   *
+   * Stream-json output consists of objects with a `type` field:
+   * - "assistant": contains text content chunks
+   * - "result": final object with session_id, total_cost_usd, usage
+   * - "tool_use": tool invocation records
+   *
+   * @param {object} chunk - Parsed JSON chunk
+   * @param {string[]} textChunks - Accumulator for assistant text
+   * @param {Array} toolCalls - Accumulator for tool call records
+   * @private
+   */
+  _handleStreamChunk(chunk, textChunks, toolCalls) {
+    switch (chunk.type) {
+      case 'assistant': {
+        // Extract text content from assistant messages
+        const content = chunk.message?.content;
+        if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type === 'text' && block.text) {
+              textChunks.push(block.text);
+            }
+          }
+        } else if (typeof content === 'string') {
+          textChunks.push(content);
+        }
+
+        // Emit typing event so Telegram adapter can refresh the indicator
+        this.emit('typing');
+        break;
+      }
+
+      case 'content_block_delta': {
+        // Incremental text deltas during streaming
+        if (chunk.delta?.type === 'text_delta' && chunk.delta.text) {
+          textChunks.push(chunk.delta.text);
+        }
+        this.emit('typing');
+        break;
+      }
+
+      case 'tool_use': {
+        toolCalls.push({
+          id: chunk.id,
+          name: chunk.name,
+          input: chunk.input,
+        });
+        break;
+      }
+
+      case 'result': {
+        // Final result object -- extract any remaining text from the result
+        const resultContent = chunk.result?.content;
+        if (Array.isArray(resultContent)) {
+          for (const block of resultContent) {
+            if (block.type === 'text' && block.text) {
+              textChunks.push(block.text);
+            }
+          }
+        }
+        break;
+      }
+
+      default:
+        // Other chunk types (e.g., "system", "thinking") are logged at debug level
+        this.logger.debug('claude', `Stream chunk type: ${chunk.type}`);
+        break;
+    }
+  }
+
+  /**
+   * Returns true if a Claude subprocess is currently running.
+   * @returns {boolean}
+   */
+  isActive() {
+    return this.activeProcess !== null && this.activeProcess.exitCode === null;
+  }
+
+  /**
+   * Kill the active Claude subprocess, if any.
+   */
+  kill() {
+    if (this.activeProcess && this.activeProcess.exitCode === null) {
+      this.logger.warn('claude', 'Killing active subprocess');
+      this.activeProcess.kill('SIGTERM');
+      this.activeProcess = null;
+    }
+  }
+}
+
+export { ClaudeBridge };
+export default ClaudeBridge;