thepopebot 1.2.75-beta.8 → 1.2.75

package/README.md

@@ -106,7 +106,7 @@ The wizard walks you through everything:
 - **Web Chat**: Visit your APP_URL to chat with your agent, create jobs, upload files
 - **Telegram** (optional): Run `npm run setup-telegram` to connect a Telegram bot
 - **Webhook**: Send a POST to `/api/create-agent-job` with your API key to create jobs programmatically
-- **Cron**: Edit `config/CRONS.json` to schedule recurring jobs
+- **Cron**: Edit `agent-job/CRONS.json` to schedule recurring jobs
 
 ### Chat vs Agent LLM
 

package/api/CLAUDE.md

@@ -26,7 +26,7 @@ Browser-facing data fetching uses **fetch route handlers** colocated with pages
 | GET | `/api/ping` | None | Health check |
 | POST | `/api/create-agent-job` | `x-api-key` | Create agent job |
 | GET | `/api/get-agent-job-secret` | `x-api-key` | Get an agent job secret; oauth2 credentials return only the access_token (auto-refreshed) |
-| POST | `/api/set-agent-job-secret` | `x-api-key` | Set/update an agent job secret (for agents to persist rotated credentials) |
+| GET | `/api/agent-job-list-secrets` | `x-api-key` | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |
 | GET | `/api/agent-jobs/status` | `x-api-key` | Agent job status (query: `?agent_job_id=`) |
 | POST | `/api/telegram/webhook` | Telegram webhook secret | Telegram message handler |
 | POST | `/api/telegram/register` | `x-api-key` | Register bot token + webhook URL |

package/api/index.js

@@ -166,20 +166,13 @@ async function handleGetAgentSecret(request) {
   return Response.json({ value: raw });
 }
 
-async function handleSetAgentSecret(request) {
+async function handleListAgentSecrets(request) {
   const record = verifyApiKey(request.headers.get('x-api-key'));
   if (record.type !== 'agent_job_api_key') {
     return Response.json({ error: 'Forbidden' }, { status: 403 });
   }
-
-  const body = await request.json();
-  const { key, value } = body;
-  if (!key || typeof value !== 'string') {
-    return Response.json({ error: 'Missing key or value' }, { status: 400 });
-  }
-  const { setAgentJobSecret } = await import('../lib/db/config.js');
-  setAgentJobSecret(key, value, 'agent');
-  return Response.json({ success: true });
+  const { listAgentJobSecrets } = await import('../lib/db/config.js');
+  return Response.json({ secrets: listAgentJobSecrets() });
 }
 
 async function handleTelegramRegister(request) {
@@ -405,7 +398,6 @@ async function POST(request) {
   // Route to handler
   switch (routePath) {
     case '/create-agent-job':     return handleCreateAgentJob(request);
-    case '/set-agent-job-secret':  return handleSetAgentSecret(request);
     case '/telegram/webhook':   return handleTelegramWebhook(request);
     case '/telegram/register':  return handleTelegramRegister(request);
     case '/github/webhook':     return handleGithubWebhook(request);
@@ -424,7 +416,8 @@ async function GET(request) {
   switch (routePath) {
     case '/ping':               return Response.json({ message: 'Pong!' });
     case '/agent-jobs/status':  return handleAgentJobStatus(request);
-    case '/get-agent-job-secret':   return handleGetAgentSecret(request);
+    case '/get-agent-job-secret':     return handleGetAgentSecret(request);
+    case '/agent-job-list-secrets':  return handleListAgentSecrets(request);
     case '/oauth/callback':     return handleOAuthCallback(request);
     default:                    return Response.json({ error: 'Not found' }, { status: 404 });
   }

package/bin/CLAUDE.md

@@ -21,7 +21,7 @@ Entry point: `cli.js` (invoked via `npx thepopebot <command>`).
 
 `managed-paths.js` defines files auto-synced by `init`. These are overwritten on every init/upgrade — users should not edit them.
 
-**Managed paths**: `.github/workflows/`, `docker-compose.yml`, `.dockerignore`, `.gitignore`, `CLAUDE.md`, `config/CLAUDE.md`, `skills/CLAUDE.md`, `cron/CLAUDE.md`, `triggers/CLAUDE.md`, `docs/CLAUDE.md`.
+**Managed paths**: `.github/workflows/`, `docker-compose.yml`, `.dockerignore`, `.gitignore`, `agent-job/CLAUDE.md`, `event-handler/CLAUDE.md`, `skills/CLAUDE.md`.
 
 `isManaged(relPath)` — returns true if a path is managed (exact match or directory prefix).
 

package/bin/cli.js

@@ -56,6 +56,8 @@ Commands:
   setup-telegram                    Reconfigure Telegram webhook
   reset-auth                        Regenerate AUTH_SECRET (invalidates all sessions)
   reset [file]                      Restore a template file (or list available templates)
+  reset-all                         Nuclear reset — restore entire project to fresh init state
+  audit                             Show project state vs. package templates (modified/missing/unknown)
   diff [file]                       Show differences between project files and package templates
   sync <path>                       Sync local package to a test install (build, pack, Docker)
   sync --fast <path>                Fast sync — copy source into running container, rebuild .next
@@ -211,10 +213,13 @@ async function init() {
             const tmplPath = templatePath(relPath, templatesDir);
             const templateExists = fs.existsSync(path.join(templatesDir, tmplPath));
             if (!templateExists) {
-              backupFile(fullPath, relPath);
-              fs.unlinkSync(fullPath);
+              const bd = getBackupDir();
+              const dest = path.join(bd, relPath);
+              fs.mkdirSync(path.dirname(dest), { recursive: true });
+              fs.renameSync(fullPath, dest);
+              backedUp.push(relPath);
               deleted.push(relPath);
-              console.log(`  Deleted ${relPath} (stale managed file)`);
+              console.log(`  Removed ${relPath} (stale managed file)`);
             }
           }
         }
@@ -273,14 +278,14 @@ async function init() {
   }
 
   // Create default skill activation symlinks
-  const defaultSkills = ['agent-job-secrets'];
+  const defaultSkills = [];
   const activeDir = path.join(cwd, 'skills', 'active');
   fs.mkdirSync(activeDir, { recursive: true });
   for (const skill of defaultSkills) {
     const symlink = path.join(activeDir, skill);
     if (!fs.existsSync(symlink)) {
-      createDirLink(`../${skill}`, symlink);
-      console.log(`  Created skills/active/${skill} → ../${skill}`);
+      createDirLink(`../library/${skill}`, symlink);
+      console.log(`  Created skills/active/${skill} → ../library/${skill}`);
     }
   }
 
@@ -370,6 +375,36 @@ THEPOPEBOT_VERSION=${version}
   console.log('\nDone! Run: npm run setup\n');
 }
 
+/**
+ * Create a timestamped backup directory and return { dir, ts }.
+ */
+function createBackupDir(cwd) {
+  const now = new Date();
+  const ts = now.getFullYear().toString()
+    + String(now.getMonth() + 1).padStart(2, '0')
+    + String(now.getDate()).padStart(2, '0')
+    + '-'
+    + String(now.getHours()).padStart(2, '0')
+    + String(now.getMinutes()).padStart(2, '0')
+    + String(now.getSeconds()).padStart(2, '0');
+  return { dir: path.join(cwd, '.backups', ts), ts };
+}
+
+/**
+ * Move a file or symlink to the backup directory.
+ */
+function backupAndRemove(fullPath, relPath, backupDir) {
+  const dest = path.join(backupDir, relPath);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (fs.lstatSync(fullPath).isSymbolicLink()) {
+    const target = fs.readlinkSync(fullPath);
+    fs.symlinkSync(target, dest);
+    fs.unlinkSync(fullPath);
+  } else {
+    fs.renameSync(fullPath, dest);
+  }
+}
+
 /**
  * List all available template files, or restore a specific one.
  */
@@ -385,7 +420,7 @@ function reset(filePath) {
       console.log(`  ${destPath(file)}`);
     }
     console.log('\nUsage: thepopebot reset <file>');
-    console.log('Example: thepopebot reset config/SOUL.md\n');
+    console.log('Example: thepopebot reset agent-job/SOUL.md\n');
     return;
   }
 
@@ -399,13 +434,38 @@ function reset(filePath) {
     process.exit(1);
   }
 
+  // Back up existing file before overwriting
+  if (fs.existsSync(dest)) {
+    const { dir, ts } = createBackupDir(cwd);
+    if (fs.statSync(src).isDirectory()) {
+      // Back up all files in the directory
+      function walkBackup(d) {
+        const items = fs.readdirSync(d, { withFileTypes: true });
+        for (const item of items) {
+          const full = path.join(d, item.name);
+          const rel = path.relative(cwd, full);
+          if (item.isDirectory()) {
+            walkBackup(full);
+          } else {
+            backupAndRemove(full, rel, dir);
+          }
+        }
+      }
+      walkBackup(dest);
+      console.log(`\n  Backed up to .backups/${ts}/`);
+    } else {
+      backupAndRemove(dest, filePath, dir);
+      console.log(`\n  Backed up to .backups/${ts}/${filePath}`);
+    }
+  }
+
   if (fs.statSync(src).isDirectory()) {
     console.log(`\nRestoring ${filePath}/...\n`);
     copyDirSyncForce(src, dest, tmplPath);
   } else {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.copyFileSync(src, dest);
-    console.log(`\nRestored ${filePath}\n`);
+    console.log(`Restored ${filePath}\n`);
   }
 }
 
@@ -442,7 +502,7 @@ function diff(filePath) {
       console.log('  All files match package templates.');
     }
     console.log('\nUsage: thepopebot diff <file>');
-    console.log('Example: thepopebot diff config/SOUL.md\n');
+    console.log('Example: thepopebot diff agent-job/SOUL.md\n');
     return;
   }
 
@@ -471,6 +531,98 @@ function diff(filePath) {
   }
 }
 
+/**
+ * Audit project state against package templates.
+ * Groups all non-protected files into: matching, modified, missing, unknown.
+ */
+function audit() {
+  const packageDir = path.join(__dirname, '..');
+  const templatesDir = path.join(packageDir, 'templates');
+  const cwd = process.cwd();
+
+  const templateFiles = getTemplateFiles(templatesDir);
+  const matching = [];
+  const modified = [];
+  const missing = [];
+
+  // Check every template file against the project
+  for (const relPath of templateFiles) {
+    const src = path.join(templatesDir, relPath);
+    const outPath = destPath(relPath);
+    const dest = path.join(cwd, outPath);
+
+    if (!fs.existsSync(dest)) {
+      missing.push(outPath);
+    } else {
+      const srcContent = fs.readFileSync(src);
+      const destContent = fs.readFileSync(dest);
+      if (srcContent.equals(destContent)) {
+        matching.push(outPath);
+      } else {
+        modified.push(outPath);
+      }
+    }
+  }
+
+  // Build a set of known template dest paths for lookup
+  const templateDestPaths = new Set(templateFiles.map(f => destPath(f)));
+
+  // Walk the project for unknown files (not in templates, not protected)
+  const unknown = [];
+  function walkProject(dir) {
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+      const fullPath = path.join(dir, item.name);
+      const relPath = path.relative(cwd, fullPath);
+      if (isProtected(relPath)) continue;
+      if (item.isDirectory() && !item.isSymbolicLink()) {
+        walkProject(fullPath);
+      } else if (!templateDestPaths.has(relPath)) {
+        unknown.push(relPath);
+      }
+    }
+  }
+  walkProject(cwd);
+
+  // Report
+  console.log('\n  Project audit\n');
+
+  if (modified.length > 0) {
+    console.log(`  Modified (${modified.length}) — template exists, your version differs:`);
+    for (const f of modified) {
+      console.log(`    ${f}`);
+    }
+    console.log('');
+  }
+
+  if (missing.length > 0) {
+    console.log(`  Missing (${missing.length}) — template exists, not in your project:`);
+    for (const f of missing) {
+      console.log(`    ${f}`);
+    }
+    console.log('');
+  }
+
+  if (unknown.length > 0) {
+    console.log(`  Unknown (${unknown.length}) — in your project, no template (reset-all would remove):`);
+    for (const f of unknown) {
+      console.log(`    ${f}`);
+    }
+    console.log('');
+  }
+
+  console.log(`  ${matching.length} file(s) match package templates.`);
+
+  if (modified.length > 0 || missing.length > 0) {
+    console.log('\n  To reset a file:     thepopebot reset <file>');
+    console.log('  To view a diff:      thepopebot diff <file>');
+  }
+  if (unknown.length > 0 || modified.length > 0 || missing.length > 0) {
+    console.log('  To reset everything: thepopebot reset-all');
+  }
+  console.log('');
+}
+
 function copyDirSyncForce(src, dest, templateRelBase = '') {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -491,6 +643,134 @@ function copyDirSyncForce(src, dest, templateRelBase = '') {
   }
 }
 
+// Paths that reset-all must never touch (relative to project root).
+// Entries ending with '/' are directory prefixes.
+const PROTECTED_PATHS = [
+  '.env',
+  '.env.local',
+  'data/',
+  'logs/',
+  '.git/',
+  '.backups/',
+  'package-lock.json',
+  'package.json',
+  'docker-compose.custom.yml',
+  '.claude/',
+  '.pi/',
+  'skills/',
+  'node_modules/',
+];
+
+function isProtected(relPath) {
+  return PROTECTED_PATHS.some(p =>
+    p.endsWith('/') ? relPath === p.slice(0, -1) || relPath.startsWith(p) : relPath === p
+  );
+}
+
+async function resetAll() {
+  const cwd = process.cwd();
+
+  // Verify this is a thepopebot project
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    console.error('\n  Not a thepopebot project (no package.json found).\n');
+    process.exit(1);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (!deps.thepopebot) {
+    console.error('\n  Not a thepopebot project (thepopebot not in dependencies).\n');
+    process.exit(1);
+  }
+
+  // Dry run — collect all files that would be moved
+  const filesToMove = [];
+  function collectFiles(dir) {
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+      const fullPath = path.join(dir, item.name);
+      const relPath = path.relative(cwd, fullPath);
+      if (isProtected(relPath)) continue;
+      if (item.isDirectory() && !item.isSymbolicLink()) {
+        collectFiles(fullPath);
+      } else {
+        filesToMove.push(relPath);
+      }
+    }
+  }
+  collectFiles(cwd);
+
+  if (filesToMove.length === 0) {
+    console.log('\n  Nothing to reset — no non-protected files found.\n');
+    return;
+  }
+
+  const { confirm, isCancel } = await import('@clack/prompts');
+
+  console.log('\n  This will reset your entire project to a fresh thepopebot init state.');
+  console.log(`  ${filesToMove.length} file(s) will be moved to .backups/:\n`);
+  for (const f of filesToMove) {
+    console.log(`    ${f}`);
+  }
+  console.log('\n  Protected (will NOT be touched):');
+  for (const p of PROTECTED_PATHS) {
+    console.log(`    ${p}`);
+  }
+
+  const ok = await confirm({ message: '\nAre you sure? This is the nuclear option.' });
+  if (isCancel(ok) || !ok) {
+    console.log('\n  Cancelled.\n');
+    return;
+  }
+
+  // Move all files to backup
+  const { dir: backupDir, ts } = createBackupDir(cwd);
+
+  for (const relPath of filesToMove) {
+    const fullPath = path.join(cwd, relPath);
+    backupAndRemove(fullPath, relPath, backupDir);
+  }
+
+  // Remove empty directories left behind
+  function removeEmptyDirs(dir) {
+    if (!fs.existsSync(dir)) return;
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+      if (item.isDirectory()) {
+        removeEmptyDirs(path.join(dir, item.name));
+      }
+    }
+    const relPath = path.relative(cwd, dir);
+    if (relPath && !isProtected(relPath) && fs.readdirSync(dir).length === 0) {
+      fs.rmdirSync(dir);
+    }
+  }
+  removeEmptyDirs(cwd);
+
+  console.log(`\n  Moved ${filesToMove.length} file(s) to .backups/${ts}/`);
+
+  // Run init to rebuild from templates
+  console.log('\n  Running init to rebuild project...\n');
+  try {
+    execSync('npx thepopebot init --no-install', { stdio: 'inherit', cwd });
+  } catch {
+    console.error('\n  Init failed. Your backup is at .backups/' + ts + '/\n');
+    process.exit(1);
+  }
+
+  // Run npm install separately
+  console.log('\nInstalling dependencies...\n');
+  try {
+    execSync('npm install', { stdio: 'inherit', cwd });
+  } catch {
+    console.error('\n  npm install failed. Your backup is at .backups/' + ts + '/\n');
+    process.exit(1);
+  }
+
+  console.log('\n  Reset complete. Project restored to fresh init state.');
+  console.log(`  Backup: .backups/${ts}/\n`);
+}
+
 function setup() {
   const setupScript = path.join(__dirname, '..', 'setup', 'setup.mjs');
   try {
@@ -801,6 +1081,12 @@ switch (command) {
   case 'reset':
     reset(args[0]);
     break;
+  case 'reset-all':
+    await resetAll();
+    break;
+  case 'audit':
+    audit();
+    break;
   case 'diff':
     diff(args[0]);
     break;

package/bin/managed-paths.js

@@ -4,16 +4,9 @@
 // Paths ending with '/' are directories (all contents are managed).
 export const MANAGED_PATHS = [
   '.github/workflows/',
-
   'docker-compose.yml',
   '.dockerignore',
   '.gitignore',
-  'CLAUDE.md',
-  'config/CLAUDE.md',
-  'skills/CLAUDE.md',
-  'cron/CLAUDE.md',
-  'triggers/CLAUDE.md',
-  'docs/',
 ];
 
 export function isManaged(relPath) {

package/config/CLAUDE.md

@@ -1,32 +1,4 @@
-# config/ — Configuration Files
-
-## Directory Structure
-
-```
-config/
-├── agent-chat/
-│   └── SYSTEM.md              # Agent chat system prompt (supports {{skills}}, {{datetime}})
-├── code-chat/
-│   └── SYSTEM.md              # Code workspace system prompt
-├── agent-job/
-│   ├── SOUL.md                # Agent personality/identity (used by Docker agent)
-│   ├── AGENT_JOB.md           # Agent runtime environment docs (used by Docker agent)
-│   └── SUMMARY.md             # Prompt for summarizing completed jobs
-├── cluster/
-│   ├── SYSTEM.md              # Cluster worker system prompt
-│   └── ROLE.md                # Per-role prompt template for cluster workers
-├── HEARTBEAT.md               # Self-monitoring behavior (cron task prompt)
-├── CRONS.json                 # Scheduled job definitions
-└── TRIGGERS.json              # Webhook trigger definitions
-```
-
-## Markdown File Includes
-
-Markdown files in `config/` support includes and built-in variables, powered by `lib/utils/render-md.js`.
-
-- **File includes**: `{{ filepath.md }}` — resolves relative to project root, recursive with circular detection. Missing files are left as-is.
-- **`{{datetime}}`** — Current ISO timestamp.
-- **`{{skills}}`** — Dynamic bullet list of active skill descriptions from `skills/active/*/SKILL.md` frontmatter. Never hardcode skill names — this is resolved at runtime.
+# config/ — Next.js Config Wrapper
 
 ## Next.js Config Wrapper (index.js)
 

package/lib/CLAUDE.md

@@ -12,16 +12,16 @@ If the task needs to *think*, use `agent`. If it just needs to *do*, use `comman
 
 **Agent**: Creates a Docker Agent job via `createAgentJob()`. Pushes an `agent-job/*` branch and launches a local Docker container. The `job` string is the LLM task prompt. Agent backend selected via `agent_backend` in `agent-job.config.json`.
 
-**Command**: Runs a shell command on the event handler. Working directory: `cron/` for crons, `triggers/` for triggers.
+**Command**: Runs a shell command on the event handler. Working directory: project root.
 
 **Webhook**: Makes an HTTP request. `GET` skips the body; `POST` (default) sends `{ ...vars }` or `{ ...vars, data: <payload> }`.
 
 ## Cron Jobs
 
-Defined in `config/CRONS.json`, loaded by `lib/cron.js` at startup via `node-cron`. Each entry has `name`, `schedule` (cron expression), `type` (`agent`/`command`/`webhook`), and the corresponding action fields (`job`, `command`, or `url`/`method`/`headers`/`vars`). Set `enabled: false` to disable. Agent-type entries support optional `llm_provider` and `llm_model` fields to override the default LLM (passed to Docker agent via `agent-job.config.json`).
+Defined in `agent-job/CRONS.json`, loaded by `lib/cron.js` at startup via `node-cron`. Each entry has `name`, `schedule` (cron expression), `type` (`agent`/`command`/`webhook`), and the corresponding action fields (`job`, `command`, or `url`/`method`/`headers`/`vars`). Set `enabled: false` to disable. Agent-type entries support optional `llm_provider` and `llm_model` fields to override the default LLM (passed to Docker agent via `agent-job.config.json`).
 
 ## Webhook Triggers
 
-Defined in `config/TRIGGERS.json`, loaded by `lib/triggers.js`. Each trigger watches an endpoint path (`watch_path`) and fires an array of actions (fire-and-forget, after auth, before route handler). Actions use the same `type`/`job`/`command`/`url` fields as cron jobs, including optional `llm_provider`/`llm_model` overrides.
+Defined in `event-handler/TRIGGERS.json`, loaded by `lib/triggers.js`. Each trigger watches an endpoint path (`watch_path`) and fires an array of actions (fire-and-forget, after auth, before route handler). Actions use the same `type`/`job`/`command`/`url` fields as cron jobs, including optional `llm_provider`/`llm_model` overrides.
 
 Template tokens in `job` and `command` strings: `{{body}}`, `{{body.field}}`, `{{query}}`, `{{query.field}}`, `{{headers}}`, `{{headers.field}}`.

package/lib/ai/CLAUDE.md

@@ -5,12 +5,12 @@
 Two agent singletons, both using `createReactAgent` from `@langchain/langgraph/prebuilt` with `SqliteSaver` for conversation memory:
 
 **Agent Chat** — singleton via `getAgentChat()`:
-- System prompt: `config/agent-chat/SYSTEM.md` (rendered fresh each invocation via `render_md()`)
+- System prompt: `event-handler/agent-chat/SYSTEM.md` (rendered fresh each invocation via `render_md()`)
 - Tools: `agent_job`, `coding_agent`
 - Call `resetAgentChats()` to clear both singletons (required if hot-reloading)
 
 **Code Chat** — singleton via `getCodeChat()`:
-- System prompt: `config/code-chat/SYSTEM.md` (rendered fresh each invocation)
+- System prompt: `event-handler/code-chat/SYSTEM.md` (rendered fresh each invocation)
 - Tools: `coding_agent` (reads repo/branch/workspace from `runtime.configurable`)
 
 ## Adding a New Tool
@@ -73,7 +73,28 @@ Three-layer parser for Claude Code agents running in headless Docker containers:
 3. **Event mapper** (`mapLine()`) — Converts each line to chat events:
    - `assistant` messages: `text` blocks → `{ type: 'text' }`, `tool_use` blocks → `{ type: 'tool-call' }`
    - `user` messages: `tool_result` blocks → `{ type: 'tool-result' }` (priority: stdout > string content > array)
-   - `result` messages: → `{ type: 'text', _resultSummary }` (injected into LangGraph memory)
+   - `result` messages: → `{ type: 'text' }` (final summary from the agent)
    - Non-JSON lines (e.g. `NO_CHANGES`, `AGENT_FAILED`): wrapped as plain text events
 
 `parseHeadlessStream(dockerLogStream)` is an async generator consuming `http.IncomingMessage`. `mapLine()` is also reused by `lib/cluster/stream.js` for worker log parsing.
+
+### Tool Return Format
+
+The `coding_agent` tool (in `tools.js`) returns the **full container session** as a flat JSON array. This becomes the ToolMessage in LangGraph's checkpoint, giving the LLM complete context on the current turn. The array contains:
+
+- `{ type: 'meta', codingAgent, backendApi }` — first event, agent identity
+- `{ type: 'text', text }` — agent text output
+- `{ type: 'tool-call', toolCallId, toolName, args }` — agent tool invocations
+- `{ type: 'tool-result', toolCallId, result }` — tool execution results
+- `{ type: 'exit', exitCode }` — last event, container exit status
+
+On error before streaming starts: `[{ type: 'error', message }]`.
+
+### Adding a New Agent Mapper (line-mappers.js)
+
+Each coding agent CLI has its own mapper function (`mapClaudeCodeLine`, `mapPiLine`, `mapGeminiLine`, `mapCodexLine`, `mapOpenCodeLine`, `mapKimiLine`). When adding a new agent:
+
+1. Create `mapXxxLine(parsed)` in `line-mappers.js` that returns an array of `{ type, ... }` events
+2. Register it in `headless-stream.js`: add to imports, re-exports, and the `mapperMap` object
+3. Map the agent's JSON output to three event types: `{ type: 'text', text }`, `{ type: 'tool-call', toolCallId, toolName, args }`, `{ type: 'tool-result', toolCallId, result }`
+4. Return `[{ type: 'skip' }]` for noise events (session init, rate limits, etc.) to suppress them without triggering the unknown fallback

package/lib/ai/agent.js

@@ -3,7 +3,8 @@ import { SystemMessage } from '@langchain/core/messages';
 import { createModel } from './model.js';
 import { agentJobTool, agentChatCodingTool, codeChatCodingTool } from './tools.js';
 import { SqliteSaver } from '@langchain/langgraph-checkpoint-sqlite';
-import { agentJobPlanningMd, codePlanningMd, thepopebotDb } from '../paths.js';
+import path from 'path';
+import { PROJECT_ROOT } from '../paths.js';
 import { render_md } from '../utils/render-md.js';
 
 // Singletons on globalThis to survive Next.js webpack chunk duplication.
@@ -20,13 +21,14 @@ export async function getAgentChat() {
     const model = await createModel();
     const tools = [agentJobTool, agentChatCodingTool];
 
-    const checkpointer = SqliteSaver.fromConnString(thepopebotDb);
+    const dbPath = process.env.DATABASE_PATH || path.join(PROJECT_ROOT, 'data/db/thepopebot.sqlite');
+    const checkpointer = SqliteSaver.fromConnString(dbPath);
 
     globalThis.__popebotAgentChat = createReactAgent({
       llm: model,
       tools,
       checkpointSaver: checkpointer,
-      prompt: (state) => [new SystemMessage(render_md(agentJobPlanningMd)), ...state.messages],
+      prompt: (state) => [new SystemMessage(render_md(path.join(PROJECT_ROOT, 'event-handler/agent-chat/SYSTEM.md'))), ...state.messages],
     });
   }
   return globalThis.__popebotAgentChat;
@@ -41,13 +43,14 @@ export async function getCodeChat() {
     const model = await createModel();
     const tools = [codeChatCodingTool];
 
-    const checkpointer = SqliteSaver.fromConnString(thepopebotDb);
+    const dbPath = process.env.DATABASE_PATH || path.join(PROJECT_ROOT, 'data/db/thepopebot.sqlite');
+    const checkpointer = SqliteSaver.fromConnString(dbPath);
 
     globalThis.__popebotCodeChat = createReactAgent({
       llm: model,
       tools,
       checkpointSaver: checkpointer,
-      prompt: (state) => [new SystemMessage(render_md(codePlanningMd)), ...state.messages],
+      prompt: (state) => [new SystemMessage(render_md(path.join(PROJECT_ROOT, 'event-handler/code-chat/SYSTEM.md'))), ...state.messages],
     });
   }
   return globalThis.__popebotCodeChat;

package/lib/ai/headless-stream.js

@@ -10,6 +10,7 @@ export {
   mapGeminiLine,
   mapCodexLine,
   mapOpenCodeLine,
+  mapKimiLine,
 } from './line-mappers.js';
 
 import {
@@ -19,6 +20,7 @@ import {
   mapGeminiLine,
   mapCodexLine,
   mapOpenCodeLine,
+  mapKimiLine,
 } from './line-mappers.js';
 
 /**
@@ -41,6 +43,7 @@ export async function* parseHeadlessStream(dockerLogStream, codingAgent = 'claud
     'gemini-cli': mapGeminiLine,
     'codex-cli': mapCodexLine,
     'opencode': mapOpenCodeLine,
+    'kimi-cli': mapKimiLine,
   };
   const mapper = mapperMap[codingAgent] || mapClaudeCodeLine;