thepopebot 1.2.76-beta.16 → 1.2.76-beta.19

package/lib/CLAUDE.md

@@ -18,10 +18,10 @@ If the task needs to *think*, use `agent`. If it just needs to *do*, use `comman
 
 ## Cron Jobs
 
-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`, `llm_model`, and `scope` fields. `scope` sets the agent's working directory to a subdirectory (e.g., `"scope": "agents/gary-vee"`) — the system prompt and skills resolve from that scope.
+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 `agent_backend`, `llm_model`, and `scope` fields. `agent_backend` picks which coding agent runs the job (e.g. `claude-code`, `codex-cli`); `llm_model` overrides the model within that agent. `scope` sets the agent's working directory to a subdirectory (e.g., `"scope": "agents/gary-vee"`) — the system prompt and skills resolve from that scope.
 
 ## Webhook Triggers
 
-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`/`scope` 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 `agent_backend`/`llm_model`/`scope` overrides.
 
 Template tokens in `job` and `command` strings: `{{body}}`, `{{body.field}}`, `{{query}}`, `{{query.field}}`, `{{headers}}`, `{{headers.field}}`.

package/lib/ai/CLAUDE.md

@@ -1,44 +1,79 @@
 # lib/ai/ — LLM Integration
 
-## Agent Types
+## Architecture
 
-Two agent singletons, both using `createReactAgent` from `@langchain/langgraph/prebuilt` with `SqliteSaver` for conversation memory:
+Every chat message flows through `chatStream()` in `index.js`. After workspace setup, it forks on whether a registered SDK adapter exists for the active coding agent:
 
-**Agent Chat** — singleton via `getAgentChat()`:
-- 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)
+- **SDK path** (`streamViaSdk`) — in-process `@anthropic-ai/claude-agent-sdk` via `sdk-adapters/claude-code.js`. Used only when `CODING_AGENT=claude-code`.
+- **Direct path** (`streamViaContainer`) — spawns the configured coding agent in an ephemeral headless Docker container via `runHeadlessContainer()`. Streams output through `parseHeadlessStream()`. Used for every agent without an SDK adapter (pi, codex, gemini, opencode, kimi).
 
-**Code Chat** — singleton via `getCodeChat()`:
-- System prompt: `event-handler/code-chat/SYSTEM.md` (rendered fresh each invocation)
-- Tools: `coding_agent` (reads repo/branch/workspace from `runtime.configurable`)
+Both paths yield the same normalized chunk shape and use the same DB persistence pattern. There is no LangGraph React agent and no intermediate LLM between the user's message and the agent.
 
-## Adding a New Tool
+## Multi-Turn Memory
 
-1. Define in `tools.js` with Zod schema (use `tool()` from `@langchain/core/tools`)
-2. Add to the agent's tools array in `agent.js`
-3. Call `resetAgentChats()` if the agent needs to pick up the new tool without restart
+Neither path persists conversation context at the LangChain/LangGraph layer — that layer is gone. Memory lives where the coding agent naturally keeps it:
+
+- **SDK path** — session ID captured from the SDK's `meta` chunk and written via `session-manager.js` (`{workspaceBaseDir}/.claude-ttyd-sessions/7681`). Passed back into the SDK on the next turn.
+- **Direct path** — `runHeadlessContainer()` passes `CONTINUE_SESSION=1` into the container. Each agent's `run.sh` reads its own port-keyed session file and resumes natively (see `docker/coding-agent/CLAUDE.md` § Session Tracking).
 
 ## Chat Modes
 
-Two primary chat modes stored in `chats.chatMode`:
+`chats.chatMode` is either `'agent'` or `'code'`:
+
+- **Agent mode** (`chatMode: 'agent'`) — repo/branch defaulted from `GH_OWNER`/`GH_REPO`, `main` branch, agent job secrets injected, system prompt built from `event-handler/agent-chat/SYSTEM.md` with scope-resolved skills.
+- **Code mode** (`chatMode: 'code'`) — user-selected repo/branch, no secret injection, system prompt from `event-handler/code-chat/SYSTEM.md`.
+
+Per-chat sub-mode via `codeModeType`:
+- **plan** — `PERMISSION=plan` (read-only).
+- **code** — `PERMISSION=code` (write/dangerous).
+
+The "job" sub-mode is no longer wired — a skill will replace autonomous job dispatch.
+
+## Chunk Shape
+
+`chatStream()` yields normalized chunks consumed by `lib/chat/api.js`:
+
+- `{ type: 'text', text }`
+- `{ type: 'tool-call', toolCallId, toolName, args }`
+- `{ type: 'tool-result', toolCallId, result }`
+- `{ type: 'error', message }` — surfaced to the UI as a red message and persisted for refresh
+- `{ type: 'meta', ... }`, `{ type: 'result', ... }` — internal, not emitted to client
+- `{ type: 'thinking-start' | 'thinking' | 'thinking-end' }` — SDK path only
+
+## Workspace Setup
+
+`ensureWorkspaceRepo()` (workspace-setup.js) is called before either path runs. It clones the repo, sets git identity, and checks out/creates the feature branch on the host — agent-agnostic. The container's `2_clone.sh` is a no-op when `.git` already exists.
+
+On the first message in a new chat, `chatStream` yields a visible `tool-call`/`tool-result` pair with `toolName: 'workspace'` so the setup appears in the UI.
 
-**Agent mode** (`chatMode: 'agent'`) — Tools: `agent_job`, `coding_agent`. Three sub-modes selected per-chat via `codeModeType` (stored in client localStorage):
-- **plan** — `coding_agent` runs in read-only permission mode
-- **code** — `coding_agent` runs in write (dangerous) permission mode
-- **job** — `agent_job` dispatches autonomous Docker container task
+## Helper LLM (`helper-llm.js`)
 
-**Code mode** (`chatMode: 'code'`) — Tool: `coding_agent` only (operates on user's selected repo). Sub-modes: plan and code (no job).
+Small one-shot completions used by the event handler itself. Independent of the coding agent — it has its own provider/model selection at `/admin/event-handler/helper-llm`.
 
-The `[chat mode: X]` suffix is appended to user messages in `index.js` so the LLM knows which tool to invoke. `codeModeType` flows through `runtime.configurable` to tools, which map it to Docker's `PERMISSION` env var (`plan` or `code`).
+**Callers:**
+- `autoTitle()` (chat title — 2-5 word title for "New Chat")
+- `summarizeAgentJob()` (webhook-triggered PR merge summary)
+- `generateAgentJobTitle()` (~10 word title for an agent job)
 
-## Model Resolution
+**API:**
+- `callHelperLlm({system, user, maxTokens})` → returns trimmed text (uses AI SDK `generateText`)
+- `callHelperLlmStructured({system, user, schema, maxTokens})` → returns parsed object (uses AI SDK `generateObject`); throws on schema/parse failure (callers catch and fall back)
 
-`createModel()` in `model.js` resolves provider/model at agent creation time (singleton for chat agent). Provider determined by `LLM_PROVIDER` config, model by `LLM_MODEL`. Changing these requires restart (or `resetAgentChats()`).
+**Provider resolution.** Reads `LLM_PROVIDER` and `LLM_MODEL` from config and builds the right AI SDK adapter:
+
+| Provider slug | AI SDK adapter |
+|---|---|
+| `anthropic` | `@ai-sdk/anthropic` |
+| `openai` | `@ai-sdk/openai` |
+| `google` | `@ai-sdk/google` |
+| built-in OpenAI-compatible (`deepseek`, `mistral`, `xai`, `kimi`, `openrouter`, `nvidia`) | `@ai-sdk/openai-compatible` with each provider's `baseUrl` from `BUILTIN_PROVIDERS` |
+| custom user-added | `@ai-sdk/openai-compatible` with the custom provider's `baseUrl` and `apiKey` |
+
+The AI SDK handles per-provider quirks (max-token param naming, thinking/reasoning block stripping, structured output via the right native mechanism per provider). Helper LLM has no LangChain dependency.
 
 ### LLM Providers
 
-Source of truth: `lib/llm-providers.js` (`BUILTIN_PROVIDERS`). Each provider declares credentials, available models, and capability flags (`chat`, `codingAgent`) that gate which models appear in which UI contexts.
+Source of truth: `lib/llm-providers.js` (`BUILTIN_PROVIDERS`).
 
 | Provider | `LLM_PROVIDER` | Default Model | Required Key |
 |----------|----------------|---------------|-------------|
@@ -52,49 +87,29 @@ Source of truth: `lib/llm-providers.js` (`BUILTIN_PROVIDERS`). Each provider dec
 | Kimi | `kimi` | `kimi-k2.5` | `MOONSHOT_API_KEY` |
 | OpenRouter | `openrouter` | (user-specified) | `OPENROUTER_API_KEY` |
 
-All credentials are stored in the settings DB (encrypted), not `.env`. Configured via `/admin/event-handler/llms` (credentials) and `/admin/event-handler/chat` (model selection).
-
-**Custom providers**: Users can add OpenAI-compatible providers via the admin UI. Stored as `type: 'llm_provider'` in the settings table. Resolved in `model.js` via `getCustomProvider()`.
-
-`LLM_MAX_TOKENS` defaults to 4096.
-
-> **Google model compatibility note:** `gemini-2.5-pro` and `gemini-3.*` models require `thought_signature` round-tripping that `@langchain/google-genai` doesn't support. Auto-falls back to `gemini-2.5-flash` with a warning (issue #201).
+All credentials are stored in the settings DB (encrypted). `LLM_MAX_TOKENS` defaults to 4096.
 
-## Chat Streaming
-
-`chatStream()` in `index.js` yields chunks: `{ type: 'text', content }`, `{ type: 'tool-call', name, args }`, `{ type: 'tool-result', name, result }`. Called by `lib/chat/api.js` (the `/stream/chat` endpoint).
+**Custom providers**: users can add OpenAI-compatible providers via `/admin/event-handler/llms`. Stored as `type: 'llm_provider'` in the settings table. Resolved at call time via `getCustomProvider()` in `helper-llm.js`.
 
 ## Headless Stream Parser (headless-stream.js)
 
-Three-layer parser for Claude Code agents running in headless Docker containers:
+Three-layer parser consumed by the direct path:
 
-1. **Docker frame decoder** — Parses 8-byte multiplexed stream headers (type + size), extracts stdout frames, discards stderr. Buffers incomplete frames across chunks.
-2. **NDJSON splitter** — Accumulates decoded UTF-8, splits on newlines. Holds incomplete trailing lines for next chunk.
-3. **Event mapper** (`mapLine()`) — Converts each line to chat events:
+1. **Docker frame decoder** — parses 8-byte multiplexed stream headers (type + size), extracts stdout frames, discards stderr.
+2. **NDJSON splitter** — accumulates decoded UTF-8 and splits on newlines.
+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' }` (final summary from the agent)
+   - `user` messages: `tool_result` blocks → `{ type: 'tool-result' }` (priority: stdout > string > array)
+   - `result` messages: → `{ type: 'text' }` (final summary)
    - 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 }]`.
+`mapLine()` is also reused by `lib/cluster/stream.js` for worker log parsing.
 
 ### 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:
+Each coding agent CLI has its own mapper (`mapClaudeCodeLine`, `mapPiLine`, `mapGeminiLine`, `mapCodexLine`, `mapOpenCodeLine`, `mapKimiLine`). To add one:
 
-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
+1. Create `mapXxxLine(parsed)` in `line-mappers.js` that returns an array of `{ type, ... }` events.
+2. Register it in `headless-stream.js`: imports, re-exports, and the `mapperMap` object.
+3. Map the agent's JSON output to the chunk shape above.
+4. Return `[{ type: 'skip' }]` for noise events to suppress them without triggering the unknown fallback.

package/lib/ai/helper-llm.js

@@ -0,0 +1,108 @@
+/**
+ * Helper LLM — small one-shot completions used by the event handler itself
+ * (chat titles, agent-job summaries, agent-job titles). Independent of the
+ * coding agent and the streaming chat path.
+ *
+ * Provider/model is set at /admin/event-handler/helper-llm and stored as
+ * LLM_PROVIDER / LLM_MODEL config keys. Credentials live in the same settings
+ * DB used by /admin/event-handler/llms.
+ */
+
+import { generateText, generateObject } from 'ai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { getConfig } from '../config.js';
+import { getCustomProvider } from '../db/config.js';
+import { BUILTIN_PROVIDERS } from '../llm-providers.js';
+
+/**
+ * Build the active LanguageModelV2 instance for helper LLM calls.
+ * Reads LLM_PROVIDER + LLM_MODEL from config and selects the right adapter.
+ *
+ * @returns {import('ai').LanguageModelV2}
+ */
+function resolveModel() {
+  const slug = getConfig('LLM_PROVIDER');
+  const modelName = getConfig('LLM_MODEL');
+  if (!slug) throw new Error('LLM_PROVIDER not configured');
+  if (!modelName) throw new Error('LLM_MODEL not configured');
+
+  if (slug === 'anthropic') {
+    return createAnthropic({ apiKey: getConfig('ANTHROPIC_API_KEY') })(modelName);
+  }
+  if (slug === 'google') {
+    return createGoogleGenerativeAI({ apiKey: getConfig('GOOGLE_API_KEY') })(modelName);
+  }
+  if (slug === 'openai') {
+    return createOpenAI({ apiKey: getConfig('OPENAI_API_KEY') })(modelName);
+  }
+
+  // Built-in OpenAI-compatible providers (deepseek, mistral, xai, kimi, openrouter, nvidia)
+  const builtin = BUILTIN_PROVIDERS[slug];
+  if (builtin) {
+    if (!builtin.baseUrl) throw new Error(`Provider ${slug} has no baseUrl`);
+    return createOpenAICompatible({
+      name: slug,
+      baseURL: builtin.baseUrl,
+      apiKey: getConfig(builtin.credentials[0].key),
+    })(modelName);
+  }
+
+  // Custom user-added OpenAI-compatible provider
+  const custom = getCustomProvider(slug);
+  if (custom) {
+    return createOpenAICompatible({
+      name: slug,
+      baseURL: custom.baseUrl,
+      apiKey: custom.apiKey || 'not-needed',
+    })(modelName);
+  }
+
+  throw new Error(`Unknown LLM provider: ${slug}`);
+}
+
+/**
+ * Plain-text helper LLM call. Returns the trimmed text.
+ *
+ * @param {object} args
+ * @param {string} args.system - System prompt
+ * @param {string} args.user - User prompt
+ * @param {number} args.maxTokens - Max output tokens
+ * @returns {Promise<string>}
+ */
+export async function callHelperLlm({ system, user, maxTokens }) {
+  const model = resolveModel();
+  const { text } = await generateText({
+    model,
+    system,
+    prompt: user,
+    maxOutputTokens: maxTokens,
+  });
+  return (text || '').trim();
+}
+
+/**
+ * Structured helper LLM call. Returns the parsed object matching the schema.
+ * Throws if the response can't be parsed or fails schema validation —
+ * callers catch and fall back as appropriate.
+ *
+ * @param {object} args
+ * @param {string} args.system - System prompt
+ * @param {string} args.user - User prompt
+ * @param {import('zod').ZodTypeAny} args.schema - Zod schema for the output
+ * @param {number} args.maxTokens - Max output tokens
+ * @returns {Promise<unknown>}
+ */
+export async function callHelperLlmStructured({ system, user, schema, maxTokens }) {
+  const model = resolveModel();
+  const { object } = await generateObject({
+    model,
+    system,
+    prompt: user,
+    schema,
+    maxOutputTokens: maxTokens,
+  });
+  return object;
+}