thepopebot 1.2.76-beta.23 → 1.2.76-beta.25

package/api/CLAUDE.md

@@ -29,7 +29,7 @@ Browser-facing data fetching uses **fetch route handlers** colocated with pages
 | Method | Path | Auth | Handler |
 |--------|------|------|---------|
 | GET | `/api/ping` | None | Health check |
-| POST | `/api/create-agent-job` | `x-api-key` | Create agent job |
+| POST | `/api/create-agent-job` | `x-api-key` | Create agent job. Body: `{ agent_job, llm_model?, agent_backend?, scope? }` |
 | GET | `/api/get-agent-job-secret` | `agent_job_api_key` only | Get an agent job secret. `oauth2` credentials return only the access_token (auto-refreshed under a lock; rotated refresh tokens are persisted back). Other secret types return the raw value. |
 | POST | `/api/set-agent-job-secret` | `agent_job_api_key` only | Create or update an agent-job secret from inside the container (used by the `set-secret` skill). |
 | GET | `/api/agent-job-list-secrets` | `x-api-key` | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |

package/api/index.js

@@ -94,13 +94,14 @@ function extractAgentJobId(branchName) {
 
 async function handleCreateAgentJob(request) {
   const body = await request.json();
-  const { job } = body;
-  if (!job) return Response.json({ error: 'Missing job field' }, { status: 400 });
+  const { agent_job } = body;
+  if (!agent_job) return Response.json({ error: 'Missing agent_job field' }, { status: 400 });
 
   try {
-    const result = await createAgentJob(job, {
+    const result = await createAgentJob(agent_job, {
       llmModel: body.llm_model,
       agentBackend: body.agent_backend,
+      scope: body.scope,
     });
     return Response.json(result);
   } catch (err) {

package/lib/actions.js

@@ -1,9 +1,6 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { createAgentJob } from './tools/create-agent-job.js';
-import { buildCodingAgentSystemPrompt } from './ai/system-prompt.js';
-import { resolveAgentScope } from './ai/scope.js';
-import { PROJECT_ROOT } from './paths.js';
 
 const execAsync = promisify(exec);
 
@@ -40,11 +37,7 @@ async function executeAction(action, opts = {}) {
   const options = {};
   if (action.llm_model) options.llmModel = action.llm_model;
   if (action.agent_backend) options.agentBackend = action.agent_backend;
-  if (action.scope) {
-    options.scope = action.scope;
-    const { skillsDir } = resolveAgentScope(PROJECT_ROOT, action.scope);
-    options.systemPrompt = buildCodingAgentSystemPrompt('agent', skillsDir, action.scope);
-  }
+  if (action.scope) options.scope = action.scope;
   const result = await createAgentJob(action.job, options);
   return `agent-job ${result.agent_job_id} — ${result.title}`;
 }

package/lib/tools/create-agent-job.js

@@ -3,6 +3,9 @@ import { z } from 'zod';
 import { githubApi } from './github.js';
 import { callHelperLlmStructured } from '../ai/helper-llm.js';
 import { getConfig } from '../config.js';
+import { resolveAgentScope } from '../ai/scope.js';
+import { buildCodingAgentSystemPrompt } from '../ai/system-prompt.js';
+import { PROJECT_ROOT } from '../paths.js';
 /**
  * Generate a short descriptive title for an agent job using the helper LLM.
  * Uses structured output to avoid thinking-token leaks with extended-thinking models.
@@ -31,6 +34,9 @@ async function generateAgentJobTitle(agentJobDescription) {
  * @param {Object} [options] - Optional overrides
  * @param {string} [options.llmModel] - LLM model override
  * @param {string} [options.agentBackend] - Agent backend override ('claude-code', 'pi', etc.)
+ * @param {string} [options.scope] - Scope subdirectory (e.g. 'agents/gary-vee'). When set,
+ *   the scope's SYSTEM.md is pre-rendered with full template resolution and stored in the
+ *   job config so the container picks it up directly (named volumes can't render host-side).
  * @returns {Promise<{agent_job_id: string, branch: string, title: string}>}
  */
 async function createAgentJob(agentJobDescription, options = {}) {
@@ -52,8 +58,11 @@ async function createAgentJob(agentJobDescription, options = {}) {
   const config = { title, job: agentJobDescription };
   if (options.llmModel) config.llm_model = options.llmModel;
   if (options.agentBackend) config.agent_backend = options.agentBackend;
-  if (options.scope) config.scope = options.scope;
-  if (options.systemPrompt) config.system_prompt = options.systemPrompt;
+  if (options.scope) {
+    config.scope = options.scope;
+    const { skillsDir } = resolveAgentScope(PROJECT_ROOT, options.scope);
+    config.system_prompt = buildCodingAgentSystemPrompt('agent', skillsDir, options.scope);
+  }
 
   const treeEntries = [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thepopebot",
-  "version": "1.2.76-beta.23",
+  "version": "1.2.76-beta.25",
   "type": "module",
   "description": "Create autonomous AI agents with a two-layer architecture: Next.js Event Handler + Docker Agent.",
   "bin": {

package/templates/skills/agent-job-tools/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: agent-job-tools
+description: Use when you need to access agent secrets, API keys, or create and manage background jobs. Supports listing keys and retrieving values, with OAuth credentials auto-refreshed. Also handles requests to "create a background job," "spawn a job," or "kick off an agent job."
+---
+
+## Usage
+
+```bash
+# List available secret keys (fetches current list from server)
+node skills/agent-job-tools/agent-job-tools.js secrets list
+
+# Get a secret value (OAuth credentials are auto-refreshed)
+node skills/agent-job-tools/agent-job-tools.js secrets get MY_CREDENTIALS
+
+# Run an agent job in the background
+node skills/agent-job-tools/agent-job-tools.js jobs create "Update the README with installation instructions"
+
+# With overrides
+node skills/agent-job-tools/agent-job-tools.js jobs create "Refactor the auth module" \
+  --llm-model claude-opus-4-7 \
+  --agent-backend claude-code \
+  --scope agents/refactor
+
+# Status of running jobs (all, or one by id)
+node skills/agent-job-tools/agent-job-tools.js jobs status
+node skills/agent-job-tools/agent-job-tools.js jobs status <agent_job_id>
+```
+
+## Important: pass-through behavior for `jobs create`
+
+The `<description>` arg becomes the new job's prompt verbatim. **Pass it through unchanged — do not summarize, condense, or rewrite the user's request before calling.** The new job's agent reads this description directly as its task. If the user gave you a multi-paragraph spec, pass the multi-paragraph spec.
+
+## Scope inheritance
+
+If the calling agent is running with a `SCOPE` env var set, `jobs create` defaults the new job to that same scope. Pass `--scope <value>` to override, or `--scope ""` to clear scope on the new job.
+
+## Notes
+
+- `AGENT_JOB_TOKEN` and `APP_URL` are injected automatically — no setup required.
+- Plain (non-OAuth) secrets are also available directly as env vars (e.g. `echo $MY_KEY`).
+- OAuth credentials must be fetched via `secrets get` — they are not available as env vars.
+- `secrets get` on an OAuth credential refreshes it server-side and returns a fresh access token.
+- If a fetched credential stops working (expired token, 401 error), call `secrets get` again to obtain a fresh one.
+- `secrets list` always fetches from the server, so it reflects secrets added after the container started.

package/templates/skills/agent-job-tools/agent-job-tools.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+const apiKey = process.env.AGENT_JOB_TOKEN;
+const appUrl = process.env.APP_URL;
+
+const args = process.argv.slice(2);
+const [category, subcommand, ...rest] = args;
+
+function usage() {
+  console.error('Usage:');
+  console.error('  agent-job-tools secrets list');
+  console.error('  agent-job-tools secrets get <key>');
+  console.error('  agent-job-tools jobs create <description> [--llm-model M] [--agent-backend B] [--scope S]');
+  console.error('  agent-job-tools jobs status [agent_job_id]');
+  process.exit(1);
+}
+
+function requireAuth() {
+  if (!apiKey) { console.error('AGENT_JOB_TOKEN not available'); process.exit(1); }
+  if (!appUrl) { console.error('APP_URL not available'); process.exit(1); }
+}
+
+async function httpJson(method, path, body) {
+  const url = `${appUrl}${path}`;
+  const opts = { method, headers: { 'x-api-key': apiKey } };
+  if (body !== undefined) {
+    opts.headers['Content-Type'] = 'application/json';
+    opts.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, opts);
+  if (!res.ok) {
+    const text = await res.text();
+    console.error(`${method} ${url} → ${res.status} ${text}`);
+    process.exit(1);
+  }
+  return res.json();
+}
+
+if (!category) usage();
+
+if (category === 'secrets') {
+  requireAuth();
+
+  if (subcommand === 'list') {
+    const json = await httpJson('GET', '/api/agent-job-list-secrets');
+    const secrets = json.secrets;
+    if (!secrets || secrets.length === 0) {
+      console.log('No agent secrets configured.');
+    } else {
+      console.log('Available secrets:');
+      secrets.forEach(s => {
+        const hint = s.secretType === 'oauth2' ? '  (OAuth — use get to fetch access token)'
+                   : s.secretType === 'oauth_token' ? '  (OAuth token — use get to fetch)'
+                   : '';
+        console.log(`  - ${s.key}${hint}`);
+      });
+      console.log('\nUse: agent-job-tools secrets get KEY_NAME');
+      console.log('If a fetched value stops working, call get again for a fresh one.');
+    }
+    process.exit(0);
+  }
+
+  if (subcommand === 'get') {
+    const key = rest[0];
+    if (!key) { console.error('Usage: agent-job-tools secrets get KEY_NAME'); process.exit(1); }
+    const json = await httpJson('GET', `/api/get-agent-job-secret?key=${encodeURIComponent(key)}`);
+    console.log(json.value);
+    process.exit(0);
+  }
+
+  console.error(`Unknown secrets subcommand: ${subcommand || '(none)'}`);
+  usage();
+}
+
+if (category === 'jobs') {
+  requireAuth();
+
+  if (subcommand === 'create') {
+    let description = null;
+    const opts = {};
+    let scopeExplicit = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === '--llm-model') opts.llm_model = rest[++i];
+      else if (arg === '--agent-backend') opts.agent_backend = rest[++i];
+      else if (arg === '--scope') { opts.scope = rest[++i]; scopeExplicit = true; }
+      else if (description === null) description = arg;
+      else { console.error(`Unexpected arg: ${arg}`); usage(); }
+    }
+    if (!description) { console.error('Missing job description'); usage(); }
+
+    if (!scopeExplicit && process.env.SCOPE) {
+      opts.scope = process.env.SCOPE;
+    }
+
+    const body = { agent_job: description };
+    if (opts.llm_model) body.llm_model = opts.llm_model;
+    if (opts.agent_backend) body.agent_backend = opts.agent_backend;
+    if (opts.scope) body.scope = opts.scope;
+
+    const json = await httpJson('POST', '/api/create-agent-job', body);
+    console.log(JSON.stringify(json, null, 2));
+    process.exit(0);
+  }
+
+  if (subcommand === 'status') {
+    const agentJobId = rest[0];
+    const qs = agentJobId ? `?agent_job_id=${encodeURIComponent(agentJobId)}` : '';
+    const json = await httpJson('GET', `/api/agent-jobs/status${qs}`);
+    console.log(JSON.stringify(json, null, 2));
+    process.exit(0);
+  }
+
+  console.error(`Unknown jobs subcommand: ${subcommand || '(none)'}`);
+  usage();
+}
+
+console.error(`Unknown category: ${category}`);
+usage();

package/templates/skills/agent-job-secrets/SKILL.md

@@ -1,23 +0,0 @@
----
-name: agent-job-secrets
-description: List and retrieve agent secrets. Plain secrets are also available as env vars. OAuth credentials are auto-refreshed on every get call.
----
-
-## Usage
-
-```bash
-# List available secret keys (fetches current list from server)
-node skills/agent-job-secrets/agent-job-secrets.js
-
-# Get a secret value (OAuth credentials are auto-refreshed)
-node skills/agent-job-secrets/agent-job-secrets.js get MY_CREDENTIALS
-```
-
-## Notes
-
-- `AGENT_JOB_TOKEN` and `APP_URL` are injected automatically — no setup required
-- Plain (non-OAuth) secrets are also available directly as env vars (e.g. `echo $MY_KEY`)
-- OAuth credentials must be fetched via `get` — they are not available as env vars
-- `get` on an OAuth credential refreshes it server-side and returns a fresh access token
-- If a fetched credential stops working (expired token, 401 error), call `get` again to obtain a fresh one
-- `list` always fetches from the server, so it reflects secrets added after the container started

package/templates/skills/agent-job-secrets/agent-job-secrets.js

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-
-const [cmd, key] = process.argv.slice(2);
-
-const apiKey = process.env.AGENT_JOB_TOKEN;
-const appUrl = process.env.APP_URL;
-
-// Default to list
-if (!cmd || cmd === 'list') {
-  if (!apiKey || !appUrl) {
-    console.log('No agent secrets available (missing AGENT_JOB_TOKEN or APP_URL).');
-    process.exit(0);
-  }
-  const url = `${appUrl}/api/agent-job-list-secrets`;
-  const res = await fetch(url, {
-    headers: { 'x-api-key': apiKey },
-  });
-  if (!res.ok) {
-    const body = await res.text();
-    console.error(`GET ${url} → ${res.status} ${body}`);
-    process.exit(1);
-  }
-  const json = await res.json();
-  const secrets = json.secrets;
-  if (!secrets || secrets.length === 0) {
-    console.log('No agent secrets configured.');
-  } else {
-    console.log('Available secrets:');
-    secrets.forEach(s => {
-      const hint = s.secretType === 'oauth2' ? '  (OAuth — use get to fetch access token)'
-                 : s.secretType === 'oauth_token' ? '  (OAuth token — use get to fetch)'
-                 : '';
-      console.log(`  - ${s.key}${hint}`);
-    });
-    console.log('\nUse: agent-job-secrets get KEY_NAME');
-    console.log('If a fetched value stops working, call get again for a fresh one.');
-  }
-  process.exit(0);
-}
-
-if (!apiKey) { console.error('AGENT_JOB_TOKEN not available'); process.exit(1); }
-if (!appUrl) { console.error('APP_URL not available'); process.exit(1); }
-
-if (cmd === 'get') {
-  if (!key) { console.error('Usage: agent-job-secrets get KEY_NAME'); process.exit(1); }
-  const url = `${appUrl}/api/get-agent-job-secret?key=${encodeURIComponent(key)}`;
-  const res = await fetch(url, {
-    headers: { 'x-api-key': apiKey },
-  });
-  if (!res.ok) {
-    const body = await res.text();
-    console.error(`GET ${url} → ${res.status} ${body}`);
-    process.exit(1);
-  }
-  const json = await res.json();
-  console.log(json.value);
-  process.exit(0);
-}
-
-console.error(`Unknown command: ${cmd}`);
-console.error('Available commands: list, get');
-process.exit(1);