thepopebot 1.0.0

package/lib/claude/index.js

@@ -0,0 +1,142 @@
+const paths = require('../paths');
+const { render_md } = require('../utils/render-md');
+
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+
+// Web search tool definition (Anthropic built-in)
+const WEB_SEARCH_TOOL = {
+  type: 'web_search_20250305',
+  name: 'web_search',
+  max_uses: 5,
+};
+
+/**
+ * Get Anthropic API key from environment
+ * @returns {string} API key
+ */
+function getApiKey() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    return process.env.ANTHROPIC_API_KEY;
+  }
+  throw new Error('ANTHROPIC_API_KEY environment variable is required');
+}
+
+/**
+ * Call Claude API
+ * @param {Array} messages - Conversation messages
+ * @param {Array} tools - Tool definitions
+ * @returns {Promise<Object>} API response
+ */
+async function callClaude(messages, tools) {
+  const apiKey = getApiKey();
+  const model = process.env.EVENT_HANDLER_MODEL || DEFAULT_MODEL;
+  const systemPrompt = render_md(paths.chatbotMd);
+
+  // Combine user tools with web search
+  const allTools = [WEB_SEARCH_TOOL, ...tools];
+
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+      'anthropic-beta': 'web-search-2025-03-05',
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages,
+      tools: allTools,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Claude API error: ${response.status} ${error}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Process a conversation turn with Claude, handling tool calls
+ * @param {string} userMessage - User's message
+ * @param {Array} history - Conversation history
+ * @param {Array} toolDefinitions - Available tools
+ * @param {Object} toolExecutors - Tool executor functions
+ * @returns {Promise<{response: string, history: Array}>}
+ */
+async function chat(userMessage, history, toolDefinitions, toolExecutors) {
+  // Add user message to history
+  const messages = [...history, { role: 'user', content: userMessage }];
+
+  let response = await callClaude(messages, toolDefinitions);
+  let assistantContent = response.content;
+
+  // Add assistant response to history
+  messages.push({ role: 'assistant', content: assistantContent });
+
+  // Handle tool use loop
+  while (response.stop_reason === 'tool_use') {
+    const toolResults = [];
+
+    for (const block of assistantContent) {
+      if (block.type === 'tool_use') {
+        // Skip web_search - it's a server-side tool executed by Anthropic
+        if (block.name === 'web_search') {
+          continue;
+        }
+
+        const executor = toolExecutors[block.name];
+        let result;
+
+        if (executor) {
+          try {
+            result = await executor(block.input);
+          } catch (err) {
+            result = { error: err.message };
+          }
+        } else {
+          result = { error: `Unknown tool: ${block.name}` };
+        }
+
+        toolResults.push({
+          type: 'tool_result',
+          tool_use_id: block.id,
+          content: JSON.stringify(result),
+        });
+      }
+    }
+
+    // If no client-side tools to execute, we're done
+    if (toolResults.length === 0) {
+      break;
+    }
+
+    // Add tool results to messages
+    messages.push({ role: 'user', content: toolResults });
+
+    // Get next response from Claude
+    response = await callClaude(messages, toolDefinitions);
+    assistantContent = response.content;
+
+    // Add new assistant response to history
+    messages.push({ role: 'assistant', content: assistantContent });
+  }
+
+  // Extract text response
+  const textBlocks = assistantContent.filter((block) => block.type === 'text');
+  const responseText = textBlocks.map((block) => block.text).join('\n');
+
+  return {
+    response: responseText,
+    history: messages,
+  };
+}
+
+module.exports = {
+  chat,
+  getApiKey,
+};

package/lib/claude/tools.js

@@ -0,0 +1,54 @@
+const { createJob } = require('../tools/create-job');
+const { getJobStatus } = require('../tools/github');
+
+const toolDefinitions = [
+  {
+    name: 'create_job',
+    description:
+      'Create an autonomous job for thepopebot to execute. Use this tool liberally - if the user asks for ANY task to be done, create a job. Jobs can handle code changes, file updates, research tasks, web scraping, data analysis, or anything requiring autonomous work. When the user explicitly asks for a job, ALWAYS use this tool. Returns the job ID and branch name.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        job_description: {
+          type: 'string',
+          description:
+            'Detailed job description including context and requirements. Be specific about what needs to be done.',
+        },
+      },
+      required: ['job_description'],
+    },
+  },
+  {
+    name: 'get_job_status',
+    description:
+      'Check status of running jobs. Returns list of active workflow runs with timing and current step. Use when user asks about job progress, running jobs, or job status.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        job_id: {
+          type: 'string',
+          description:
+            'Optional: specific job ID to check. If omitted, returns all running jobs.',
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+const toolExecutors = {
+  create_job: async (input) => {
+    const result = await createJob(input.job_description);
+    return {
+      success: true,
+      job_id: result.job_id,
+      branch: result.branch,
+    };
+  },
+  get_job_status: async (input) => {
+    const result = await getJobStatus(input.job_id);
+    return result;
+  },
+};
+
+module.exports = { toolDefinitions, toolExecutors };

package/lib/cron.js

@@ -0,0 +1,60 @@
+const cron = require('node-cron');
+const fs = require('fs');
+const paths = require('./paths');
+
+const { executeAction } = require('./actions');
+
+/**
+ * Load and schedule crons from CRONS.json
+ * @returns {Array} - Array of scheduled cron tasks
+ */
+function loadCrons() {
+  const cronFile = paths.cronsFile;
+
+  console.log('\n--- Cron Jobs ---');
+
+  if (!fs.existsSync(cronFile)) {
+    console.log('No CRONS.json found');
+    console.log('-----------------\n');
+    return [];
+  }
+
+  const crons = JSON.parse(fs.readFileSync(cronFile, 'utf8'));
+  const tasks = [];
+
+  for (const cronEntry of crons) {
+    const { name, schedule, type = 'agent', enabled } = cronEntry;
+    if (enabled === false) continue;
+
+    if (!cron.validate(schedule)) {
+      console.error(`Invalid schedule for "${name}": ${schedule}`);
+      continue;
+    }
+
+    const task = cron.schedule(schedule, async () => {
+      try {
+        const result = await executeAction(cronEntry, { cwd: paths.cronDir });
+        console.log(`[CRON] ${name}: ${result || 'ran'}`);
+        console.log(`[CRON] ${name}: completed!`);
+      } catch (err) {
+        console.error(`[CRON] ${name}: error - ${err.message}`);
+      }
+    });
+
+    tasks.push({ name, schedule, type, task });
+  }
+
+  if (tasks.length === 0) {
+    console.log('No active cron jobs');
+  } else {
+    for (const { name, schedule, type } of tasks) {
+      console.log(`  ${name}: ${schedule} (${type})`);
+    }
+  }
+
+  console.log('-----------------\n');
+
+  return tasks;
+}
+
+module.exports = { loadCrons };

package/lib/paths.js

@@ -0,0 +1,30 @@
+const path = require('path');
+
+/**
+ * Central path resolver for thepopebot.
+ * All paths resolve from process.cwd() (the user's project root).
+ */
+
+const PROJECT_ROOT = process.cwd();
+
+module.exports = {
+  PROJECT_ROOT,
+
+  // operating_system/ files
+  operatingSystemDir: path.join(PROJECT_ROOT, 'operating_system'),
+  cronsFile: path.join(PROJECT_ROOT, 'operating_system', 'CRONS.json'),
+  triggersFile: path.join(PROJECT_ROOT, 'operating_system', 'TRIGGERS.json'),
+  chatbotMd: path.join(PROJECT_ROOT, 'operating_system', 'CHATBOT.md'),
+  jobSummaryMd: path.join(PROJECT_ROOT, 'operating_system', 'JOB_SUMMARY.md'),
+  soulMd: path.join(PROJECT_ROOT, 'operating_system', 'SOUL.md'),
+
+  // Working directories for command-type actions
+  cronDir: path.join(PROJECT_ROOT, 'cron'),
+  triggersDir: path.join(PROJECT_ROOT, 'triggers'),
+
+  // Logs
+  logsDir: path.join(PROJECT_ROOT, 'logs'),
+
+  // .env
+  envFile: path.join(PROJECT_ROOT, '.env'),
+};

package/lib/tools/create-job.js

@@ -0,0 +1,40 @@
+const { v4: uuidv4 } = require('uuid');
+const { githubApi } = require('./github');
+
+/**
+ * Create a new job branch with updated job.md
+ * @param {string} jobDescription - The job description to write to job.md
+ * @returns {Promise<{job_id: string, branch: string}>} - Job ID and branch name
+ */
+async function createJob(jobDescription) {
+  const { GH_OWNER, GH_REPO } = process.env;
+  const jobId = uuidv4();
+  const branch = `job/${jobId}`;
+
+  // 1. Get main branch SHA
+  const mainRef = await githubApi(`/repos/${GH_OWNER}/${GH_REPO}/git/ref/heads/main`);
+  const mainSha = mainRef.object.sha;
+
+  // 2. Create new branch
+  await githubApi(`/repos/${GH_OWNER}/${GH_REPO}/git/refs`, {
+    method: 'POST',
+    body: JSON.stringify({
+      ref: `refs/heads/${branch}`,
+      sha: mainSha,
+    }),
+  });
+
+  // 3. Create logs/${jobId}/job.md with job content
+  await githubApi(`/repos/${GH_OWNER}/${GH_REPO}/contents/logs/${jobId}/job.md`, {
+    method: 'PUT',
+    body: JSON.stringify({
+      message: `job: ${jobId}`,
+      content: Buffer.from(jobDescription).toString('base64'),
+      branch: branch,
+    }),
+  });
+
+  return { job_id: jobId, branch };
+}
+
+module.exports = { createJob };

package/lib/tools/github.js

@@ -0,0 +1,122 @@
+/**
+ * GitHub REST API helper with authentication
+ * @param {string} endpoint - API endpoint (e.g., '/repos/owner/repo/...')
+ * @param {object} options - Fetch options (method, body, headers)
+ * @returns {Promise<object>} - Parsed JSON response
+ */
+async function githubApi(endpoint, options = {}) {
+  const { GH_TOKEN } = process.env;
+  const res = await fetch(`https://api.github.com${endpoint}`, {
+    ...options,
+    headers: {
+      'Authorization': `Bearer ${GH_TOKEN}`,
+      'Accept': 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      ...options.headers,
+    },
+  });
+
+  if (!res.ok) {
+    const error = await res.text();
+    throw new Error(`GitHub API error: ${res.status} ${error}`);
+  }
+
+  return res.json();
+}
+
+/**
+ * Get workflow runs with optional status filter
+ * @param {string} [status] - Filter by status (in_progress, queued, completed)
+ * @returns {Promise<object>} - Workflow runs response
+ */
+async function getWorkflowRuns(status) {
+  const { GH_OWNER, GH_REPO } = process.env;
+  const params = new URLSearchParams();
+  if (status) params.set('status', status);
+  params.set('per_page', '20');
+
+  const query = params.toString();
+  return githubApi(`/repos/${GH_OWNER}/${GH_REPO}/actions/runs?${query}`);
+}
+
+/**
+ * Get jobs for a specific workflow run
+ * @param {number} runId - Workflow run ID
+ * @returns {Promise<object>} - Jobs response with steps
+ */
+async function getWorkflowRunJobs(runId) {
+  const { GH_OWNER, GH_REPO } = process.env;
+  return githubApi(`/repos/${GH_OWNER}/${GH_REPO}/actions/runs/${runId}/jobs`);
+}
+
+/**
+ * Get job status for running/recent jobs
+ * @param {string} [jobId] - Optional specific job ID to filter by
+ * @returns {Promise<object>} - Status summary with jobs array
+ */
+async function getJobStatus(jobId) {
+  // Fetch both in_progress and queued runs
+  const [inProgress, queued] = await Promise.all([
+    getWorkflowRuns('in_progress'),
+    getWorkflowRuns('queued'),
+  ]);
+
+  const allRuns = [...(inProgress.workflow_runs || []), ...(queued.workflow_runs || [])];
+
+  // Filter to only job/* branches
+  const jobRuns = allRuns.filter(run => run.head_branch?.startsWith('job/'));
+
+  // If specific job requested, filter further
+  const filteredRuns = jobId
+    ? jobRuns.filter(run => run.head_branch === `job/${jobId}`)
+    : jobRuns;
+
+  // Get detailed job info for each run
+  const jobs = await Promise.all(
+    filteredRuns.map(async (run) => {
+      const extractedJobId = run.head_branch.slice(4); // Remove 'job/' prefix
+      const startedAt = new Date(run.created_at);
+      const durationMinutes = Math.round((Date.now() - startedAt.getTime()) / 60000);
+
+      let currentStep = null;
+      let stepsCompleted = 0;
+      let stepsTotal = 0;
+
+      try {
+        const jobsData = await getWorkflowRunJobs(run.id);
+        if (jobsData.jobs?.length > 0) {
+          const job = jobsData.jobs[0];
+          stepsTotal = job.steps?.length || 0;
+          stepsCompleted = job.steps?.filter(s => s.status === 'completed').length || 0;
+          currentStep = job.steps?.find(s => s.status === 'in_progress')?.name || null;
+        }
+      } catch (err) {
+        // Jobs endpoint may fail if run hasn't started yet
+      }
+
+      return {
+        job_id: extractedJobId,
+        branch: run.head_branch,
+        status: run.status,
+        started_at: run.created_at,
+        duration_minutes: durationMinutes,
+        current_step: currentStep,
+        steps_completed: stepsCompleted,
+        steps_total: stepsTotal,
+        run_id: run.id,
+      };
+    })
+  );
+
+  // Count only job/* branches, not all workflows
+  const runningCount = jobs.filter(j => j.status === 'in_progress').length;
+  const queuedCount = jobs.filter(j => j.status === 'queued').length;
+
+  return {
+    jobs,
+    queued: queuedCount,
+    running: runningCount,
+  };
+}
+
+module.exports = { githubApi, getWorkflowRuns, getWorkflowRunJobs, getJobStatus };

package/lib/tools/openai.js

@@ -0,0 +1,35 @@
+/**
+ * Check if Whisper transcription is enabled
+ * @returns {boolean}
+ */
+function isWhisperEnabled() {
+  return Boolean(process.env.OPENAI_API_KEY);
+}
+
+/**
+ * Transcribe audio using OpenAI Whisper API
+ * @param {Buffer} audioBuffer - Audio file buffer
+ * @param {string} filename - Original filename (e.g., "voice.ogg")
+ * @returns {Promise<string>} Transcribed text
+ */
+async function transcribeAudio(audioBuffer, filename) {
+  const formData = new FormData();
+  formData.append('file', new Blob([audioBuffer]), filename);
+  formData.append('model', 'whisper-1');
+
+  const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}` },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`OpenAI API error: ${response.status} ${error}`);
+  }
+
+  const result = await response.json();
+  return result.text;
+}
+
+module.exports = { isWhisperEnabled, transcribeAudio };