thepopebot 1.2.76-beta.2 → 1.2.76-beta.21

package/lib/ai/line-mappers.js

@@ -29,6 +29,8 @@ export function mapLine(line, mapper = mapClaudeCodeLine) {
   try {
     parsed = JSON.parse(line);
   } catch {
+    // Suppress entrypoint.sh step markers ("→ Setup Git", "→ Clone", ...)
+    if (line.startsWith('→ ')) return [{ type: 'skip' }];
     console.warn('[line-mappers] JSON parse failed, length:', line.length, 'preview:', line.slice(0, 120));
     // Non-JSON lines (NO_CHANGES, PUSH_SUCCESS, AGENT_FAILED, etc.)
     return [{ type: 'text', text: `\n${line}\n` }];
@@ -116,15 +118,16 @@ export function mapClaudeCodeLine(parsed) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Pi Coding Agent: --mode json
 //
-// Event types:
-//   session, agent_start, agent_end
-//   turn_start, turn_end
-//   message_start, message_update, message_end
-//   tool_execution_start, tool_execution_update, tool_execution_end
+// Top-level event types:
+//   session, agent_start, agent_end           — session/lifecycle (skip)
+//   turn_start, turn_end                      — turn lifecycle (skip)
+//   message_start, message_update, message_end — message lifecycle
+//   tool_execution_start/update/end           — tool execution
 //
 // message_update.assistantMessageEvent subtypes:
-//   text_start, text_delta, text_end
-//   toolcall_start, toolcall_delta, toolcall_end
+//   text_start, text_delta, text_end          — only text_delta carries new content
+//   thinking_start, thinking_delta, thinking_end — extended-thinking blocks
+//   toolcall_start, toolcall_delta, toolcall_end — only toolcall_end carries complete args
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -136,22 +139,51 @@ export function mapPiLine(parsed) {
   const events = [];
   const { type } = parsed;
 
+  // Lifecycle / session noise — skip silently so they don't render as Unknown Events
+  if (
+    type === 'session' ||
+    type === 'agent_start' ||
+    type === 'agent_end' ||
+    type === 'turn_start' ||
+    type === 'turn_end' ||
+    type === 'message_start' ||
+    type === 'message_end' ||
+    type === 'tool_execution_start' ||
+    type === 'tool_execution_update'
+  ) {
+    return [{ type: 'skip' }];
+  }
+
   if (type === 'message_update' && parsed.assistantMessageEvent) {
     const evt = parsed.assistantMessageEvent;
 
-    // Text streaming
+    // Text streaming — deltas are authoritative; start/end are lifecycle only
     if (evt.type === 'text_delta' && evt.delta) {
       events.push({ type: 'text', text: evt.delta });
+    } else if (evt.type === 'text_start' || evt.type === 'text_end') {
+      return [{ type: 'skip' }];
+    }
+
+    // Extended-thinking streaming — map to UI thinking chunks (rendered as a
+    // collapsible ephemeral card by api.js, never persisted)
+    else if (evt.type === 'thinking_start') {
+      events.push({ type: 'thinking-start' });
+    } else if (evt.type === 'thinking_delta' && evt.delta) {
+      events.push({ type: 'thinking', delta: evt.delta });
+    } else if (evt.type === 'thinking_end') {
+      events.push({ type: 'thinking-end' });
     }
 
-    // Tool call — emit on toolcall_end when we have complete args
-    if (evt.type === 'toolcall_end' && evt.toolCall) {
+    // Tool call — emit once on toolcall_end with complete args. Start/delta are skipped.
+    else if (evt.type === 'toolcall_end' && evt.toolCall) {
       events.push({
         type: 'tool-call',
         toolCallId: evt.toolCall.id,
         toolName: evt.toolCall.name,
         args: evt.toolCall.arguments || {},
       });
+    } else if (evt.type === 'toolcall_start' || evt.type === 'toolcall_delta') {
+      return [{ type: 'skip' }];
     }
   }
 
@@ -167,20 +199,6 @@ export function mapPiLine(parsed) {
     });
   }
 
-  // Final summary
-  else if (type === 'agent_end' && parsed.messages) {
-    const lastAssistant = [...parsed.messages].reverse().find(m => m.role === 'assistant');
-    if (lastAssistant) {
-      const text = (lastAssistant.content || [])
-        .filter(b => b.type === 'text')
-        .map(b => b.text)
-        .join('');
-      if (text) {
-        events.push({ type: 'text', text });
-      }
-    }
-  }
-
   return events;
 }
 

package/lib/ai/scope.js

@@ -0,0 +1,26 @@
+import path from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * Resolve working directory and skills directory for a given agent scope.
+ *
+ * @param {string} repoRoot - Absolute path to the git repo root
+ * @param {string|null} scope - Relative subdirectory path (e.g., 'agents/gary-v') or null/empty for root
+ * @returns {{ workingDir: string, skillsDir: string|null }}
+ */
+export function resolveAgentScope(repoRoot, scope) {
+  const workingDir = scope ? path.join(repoRoot, scope) : repoRoot;
+
+  // Skills: check scoped dir first, fall back to repo root
+  const scopedSkills = path.join(workingDir, 'skills');
+  const rootSkills = path.join(repoRoot, 'skills');
+
+  let skillsDir = null;
+  if (existsSync(scopedSkills)) {
+    skillsDir = scopedSkills;
+  } else if (existsSync(rootSkills)) {
+    skillsDir = rootSkills;
+  }
+
+  return { workingDir, skillsDir };
+}

package/lib/ai/sdk-adapters/CLAUDE.md

@@ -0,0 +1,114 @@
+# lib/ai/sdk-adapters/ — SDK Adapter System
+
+In-process SDK adapters that run a coding agent's SDK directly (no container) and yield a unified chunk stream consumed by `chatStream()` in `lib/ai/index.js`. Used when the active coding agent has a registered adapter; otherwise `chatStream()` uses the direct headless-container path.
+
+## Architecture
+
+```
+Browser → POST /stream/chat (api.js)
+  → chatStream() (index.js)
+    → workspace setup (ensureWorkspaceRepo)
+    → getSdkAdapter() returns adapter function or null
+    → if adapter: streamViaSdk — in-process SDK call, yields normalized chunks
+    → if null:    streamViaContainer — headless Docker container, parseHeadlessStream yields chunks
+```
+
+The adapter is a pure stream translator — it receives a prompt and options, calls the SDK, and yields normalized chunks. Everything else (workspace setup, DB persistence, session continuity, system prompts) is handled by `chatStream()` in `index.js`.
+
+## Existing Adapter
+
+| File | Agent | SDK |
+|------|-------|-----|
+| `claude-code.js` | `claude-code` | `@anthropic-ai/claude-agent-sdk` |
+
+## Adding a New SDK Adapter
+
+### 1. Create the adapter file
+
+Create `{agent-name}.js` in this directory. Export a single async generator function:
+
+```js
+export async function* myAgentStream({ prompt, workspaceDir, systemPrompt, sessionId, permissionMode, attachments }) {
+  // ... call the SDK, yield chunks
+}
+```
+
+### 2. Required chunk types to yield
+
+The adapter MUST yield these chunk types for `chatStream()` and `api.js` to work correctly:
+
+| Chunk | Shape | When | Purpose |
+|-------|-------|------|---------|
+| `meta` | `{ type: 'meta', sessionId: string }` | First event | Session ID for continuity across messages. `chatStream()` writes this to disk via `writeSessionId()` so subsequent messages resume the session. |
+| `text` | `{ type: 'text', text: string }` | Text output | Streamed to UI as deltas. Accumulated by `chatStream()` and flushed to DB as assistant messages at tool boundaries and stream end. |
+| `tool-call` | `{ type: 'tool-call', toolCallId: string, toolName: string, args: object }` | Tool invocation starts | Triggers tool UI in the browser. May be yielded twice: once at start with `args: {}`, once at `content_block_stop` with complete args. `chatStream()` tracks these in `pendingToolCalls` for pairing with results. |
+| `tool-result` | `{ type: 'tool-result', toolCallId: string, result: string }` | Tool completes | Paired with the matching `tool-call` by `toolCallId`. `chatStream()` persists the pair as a `tool-invocation` JSON message in the DB. |
+| `result` | `{ type: 'result', text: string, cost?: number, duration?: number, subtype?: string }` | Stream ends | Final summary. Logged by `chatStream()`, not persisted or sent to UI. |
+
+Optional:
+| `unknown` | `{ type: 'unknown', raw: any }` | Unrecognized events | `api.js` renders these as collapsible boxes in the UI. Use for debugging unhandled SDK events. |
+
+### 3. Register in index.js
+
+Add the import and mapping in `getSdkAdapter()`:
+
+```js
+import { myAgentStream } from './my-agent.js';
+
+export function getSdkAdapter(agentType) {
+  if (agentType === 'claude-code') return claudeCodeStream;
+  if (agentType === 'my-agent') return myAgentStream;
+  return null;
+}
+```
+
+The `agentType` string comes from the `CODING_AGENT` config value set in the admin UI.
+
+### 4. Auth resolution
+
+Use `buildAgentAuthEnv(agentType)` from `lib/tools/docker.js` to get credentials from the settings DB. This returns `{ env: string[], backendApi: string }` where `env` is an array of `KEY=value` strings. Parse them into an env object:
+
+```js
+import { buildAgentAuthEnv } from '../../tools/docker.js';
+
+const env = { ...process.env };
+const { env: authEnvPairs } = buildAgentAuthEnv('my-agent');
+for (const pair of authEnvPairs) {
+  const eqIdx = pair.indexOf('=');
+  if (eqIdx > 0) env[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+}
+```
+
+The agent's auth config (API keys, OAuth tokens, provider selection) is managed in the admin UI at `/admin/event-handler/coding-agents` and stored in the settings DB. `buildAgentAuthEnv()` reads it — you don't need to access the settings DB directly.
+
+### 5. Function parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `prompt` | `string` | User message text |
+| `workspaceDir` | `string` | Absolute path to git repo root (the SDK should execute here) |
+| `systemPrompt` | `string\|null` | System prompt for agent mode (null in code mode) |
+| `sessionId` | `string\|null` | Previous session ID to resume (null on first message) |
+| `permissionMode` | `string` | `'plan'` (read-only) or `'code'` (read-write). Map to the SDK's equivalent permission concept. |
+| `attachments` | `Array` | Image attachments: `{ category: 'image', mimeType, dataUrl }` |
+
+### 6. Session continuity contract
+
+Multi-turn conversation works via session IDs:
+
+1. First message: `sessionId` param is `null`. Adapter yields `{ type: 'meta', sessionId: '<new-id>' }`.
+2. `chatStream()` writes the session ID to `{workspaceBaseDir}/.claude-ttyd-sessions/7681`.
+3. Next message: `sessionId` param contains the saved ID. Adapter passes it to the SDK's resume mechanism.
+
+If the SDK doesn't support session resume, the adapter can ignore `sessionId` — but multi-turn context will be lost between messages.
+
+## What the adapter does NOT handle
+
+These are managed by `chatStream()` in `index.js` — adapters should not duplicate them:
+
+- **Workspace git setup** — `ensureWorkspaceRepo()` clones/checkouts before the adapter is called
+- **DB persistence** — `chatStream()` saves user messages, assistant text, and tool invocations
+- **Chat creation** — `chatStream()` creates the chat and workspace DB records
+- **Auto-titling** — `chatStream()` generates a title after the first message
+- **System prompt loading** — `chatStream()` calls `buildCodingAgentSystemPrompt()` and passes the result as `systemPrompt`
+- **Skill activation** — `ensureSkills()` runs before the adapter is called

package/lib/ai/sdk-adapters/claude-code.js

@@ -1,6 +1,10 @@
+import path from 'path';
+import fs from 'fs';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { getConfig } from '../../config.js';
 import { buildAgentAuthEnv } from '../../tools/docker.js';
+import { createAgentJobApiKey } from '../../db/api-keys.js';
+import { getAllAgentJobSecrets } from '../../db/config.js';
 
 /**
  * Claude Agent SDK adapter. Wraps the SDK's query() and yields
@@ -15,10 +19,72 @@ import { buildAgentAuthEnv } from '../../tools/docker.js';
  * @param {Array} [opts.attachments] - Image attachments
  * @yields {{ type: 'text'|'tool-call'|'tool-result'|'meta'|'result'|'unknown', ... }}
  */
-export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, sessionId, permissionMode, attachments }) {
+/**
+ * Encode an absolute path the same way Claude Code encodes cwd for session storage.
+ * Non-alphanumeric characters are replaced with '-'.
+ */
+function encodeCwd(absolutePath) {
+  return absolutePath.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * Ensure the interactive container can find SDK-created sessions on the shared volume.
+ *
+ * The SDK stores sessions at $HOME/.claude/projects/<encoded-cwd>/. The interactive
+ * container uses cwd=/home/coding-agent/workspace[/scope], but the SDK adapter uses
+ * cwd=/app/data/workspaces/workspace-XXX/workspace[/scope] — different encoded paths.
+ *
+ * Creates a symlink so the interactive container's encoded path resolves to the
+ * SDK adapter's encoded path, both on the same volume.
+ *
+ * @param {string} wsBaseDir - Volume root (e.g., /app/data/workspaces/workspace-XXX)
+ * @param {string} sdkCwd - SDK's working directory (scoped, e.g., .../workspace/agents/gary-vee)
+ * @param {string} interactiveCwd - Interactive container's equivalent cwd (e.g., /home/coding-agent/workspace/agents/gary-vee)
+ */
+function ensureSessionSymlink(wsBaseDir, sdkCwd, interactiveCwd) {
+  const projectsDir = path.join(wsBaseDir, '.claude', 'projects');
+  const sdkEncoded = encodeCwd(sdkCwd);
+  const interactiveEncoded = encodeCwd(interactiveCwd);
+
+  // Both point to the same dir — no symlink needed
+  if (sdkEncoded === interactiveEncoded) return;
+
+  fs.mkdirSync(path.join(projectsDir, sdkEncoded), { recursive: true });
+
+  const symlinkPath = path.join(projectsDir, interactiveEncoded);
+  try {
+    const existing = fs.readlinkSync(symlinkPath);
+    if (existing === sdkEncoded) return; // already correct
+    fs.unlinkSync(symlinkPath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      // It's a real directory (not a symlink) — don't touch it
+      if (err.code === 'EINVAL') return;
+    }
+  }
+
+  try {
+    fs.symlinkSync(sdkEncoded, symlinkPath);
+  } catch {}
+}
+
+export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, sessionId, permissionMode, attachments, workspaceId, chatMode }) {
+  // Point HOME at the workspace volume root (always one level above 'workspace/').
+  // workspaceDir may be scoped (e.g., .../workspace/agents/gary-vee), so we can't
+  // use path.dirname — derive from workspaceId instead.
+  const { workspaceDir: getWsDir } = await import('../../tools/docker.js');
+  const wsBaseDir = getWsDir(workspaceId);
+
+  // Build the interactive container's equivalent cwd for session symlink
+  const repoRoot = path.join(wsBaseDir, 'workspace');
+  const scope = workspaceDir.startsWith(repoRoot) ? workspaceDir.slice(repoRoot.length) : '';
+  const interactiveCwd = '/home/coding-agent/workspace' + scope;
+  ensureSessionSymlink(wsBaseDir, workspaceDir, interactiveCwd);
+
   // Build a local env object with auth credentials from the settings DB.
   // Passed via the SDK's `env` option — no process.env mutation needed.
   const env = { ...process.env };
+  env.HOME = wsBaseDir;
   try {
     const { env: authEnvPairs } = buildAgentAuthEnv('claude-code');
     for (const pair of authEnvPairs) {
@@ -41,16 +107,41 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
     // Fall through — env may already have the right vars from process.env
   }
 
+  // Inject agent job secrets when in agent chat mode
+  if (chatMode === 'agent') {
+    const shortId = (workspaceId || '').replace(/-/g, '').slice(0, 8);
+    const { key: agentJobToken } = createAgentJobApiKey(`claude-code-sdk-${shortId}`);
+    env.AGENT_JOB_TOKEN = agentJobToken;
+    const appUrl = getConfig('APP_URL');
+    if (appUrl) env.APP_URL = appUrl;
+
+    // Inject plain secrets as env vars (oauth types are null — agent fetches via skill)
+    const jobSecrets = getAllAgentJobSecrets();
+    for (const { key, value } of jobSecrets) {
+      if (value !== null && !env[key]) {
+        env[key] = value;
+      }
+    }
+  }
+
+  // Work around SDK musl/glibc detection bug — force glibc binary on Linux
+  let executablePath;
+  if (process.platform === 'linux') {
+    try {
+      executablePath = require.resolve(`@anthropic-ai/claude-agent-sdk-linux-${process.arch}/claude`);
+    } catch {}
+  }
+
   const options = {
     cwd: workspaceDir,
     env,
     includePartialMessages: true,
+    model: getConfig('CODING_AGENT_CLAUDE_CODE_MODEL') || undefined,
+    ...(executablePath ? { pathToClaudeCodeExecutable: executablePath } : {}),
   };
 
-  // Permission mode → allowed tools
-  if (permissionMode === 'code') {
-    options.permissionMode = 'bypassPermissions';
-  }
+  // Permission mode: plan = read-only, anything else = full write access
+  options.permissionMode = permissionMode === 'plan' ? 'plan' : 'bypassPermissions';
 
   if (sessionId) options.resume = sessionId;
   if (systemPrompt) {
@@ -80,6 +171,8 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
 
   // Track tool call state for mapping stream events
   const activeToolCalls = new Map(); // index → { id, name, argsJson }
+  const toolNamesById = new Map(); // toolCallId → toolName (persists for tool-result lookup)
+  const activeThinkingBlocks = new Set(); // indices of active thinking blocks
 
   try {
     for await (const message of query({ prompt: sdkPrompt, options })) {
@@ -102,9 +195,13 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
           const block = event.content_block;
           if (block.type === 'tool_use') {
             activeToolCalls.set(event.index, { id: block.id, name: block.name, argsJson: '' });
+            toolNamesById.set(block.id, block.name);
             yield { type: 'tool-call', toolCallId: block.id, toolName: block.name, args: {} };
+          } else if (block.type === 'thinking') {
+            activeThinkingBlocks.add(event.index);
+            yield { type: 'thinking-start' };
           }
-          // Skip 'thinking', 'text' start (deltas handle text)
+          // Skip 'text' start (deltas handle text)
           continue;
         }
 
@@ -114,11 +211,17 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
           } else if (event.delta.type === 'input_json_delta') {
             const tc = activeToolCalls.get(event.index);
             if (tc) tc.argsJson += event.delta.partial_json;
+          } else if (event.delta.type === 'thinking_delta') {
+            yield { type: 'thinking', delta: event.delta.thinking };
           }
           continue;
         }
 
         if (event.type === 'content_block_stop') {
+          if (activeThinkingBlocks.has(event.index)) {
+            activeThinkingBlocks.delete(event.index);
+            yield { type: 'thinking-end' };
+          }
           const tc = activeToolCalls.get(event.index);
           if (tc && tc.argsJson) {
             try {
@@ -144,14 +247,23 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
               : Array.isArray(block.content)
                 ? block.content.map(b => b.type === 'text' ? b.text : JSON.stringify(b)).join('\n')
                 : JSON.stringify(block.content);
-            yield { type: 'tool-result', toolCallId: block.tool_use_id, result: content };
+            yield { type: 'tool-result', toolCallId: block.tool_use_id, toolName: toolNamesById.get(block.tool_use_id), result: content };
           }
         }
         continue;
       }
 
       // ── assistant messages — redundant with streaming, skip ──
-      if (message.type === 'assistant') continue;
+      // But extract tool names so resumed tool-results can carry them.
+      if (message.type === 'assistant') {
+        const blocks = message.message?.content || [];
+        for (const block of blocks) {
+          if (block.type === 'tool_use' && block.id && block.name) {
+            toolNamesById.set(block.id, block.name);
+          }
+        }
+        continue;
+      }
 
       // ── result ──
       if (message.type === 'result') {

package/lib/ai/system-prompt.js

@@ -0,0 +1,34 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import { PROJECT_ROOT } from '../paths.js';
+import { render_md } from '../utils/render-md.js';
+
+/**
+ * Build the system prompt for a coding agent.
+ * @param {'agent'|'code'} mode - Chat mode
+ * @param {string|null} [skillsDir] - Skills directory for {{skills}} resolution.
+ * @param {string|null} [scope] - Agent scope (e.g., 'agents/gary-vee'). When set,
+ *   looks for SYSTEM.md in the scoped directory first, falls back to agent-job/SYSTEM.md.
+ * @returns {string|null} Rendered system prompt, or null if not configured
+ */
+export function buildCodingAgentSystemPrompt(mode, skillsDir, scope) {
+  let file;
+
+  if (mode === 'agent') {
+    // Check scoped SYSTEM.md first, fall back to agent-job/SYSTEM.md
+    if (scope) {
+      const scopedFile = path.join(PROJECT_ROOT, scope, 'SYSTEM.md');
+      if (existsSync(scopedFile)) {
+        file = scopedFile;
+      }
+    }
+    if (!file) {
+      file = path.join(PROJECT_ROOT, 'agent-job/SYSTEM.md');
+    }
+  } else {
+    file = path.join(PROJECT_ROOT, 'coding-workspace/SYSTEM.md');
+  }
+
+  const rendered = render_md(file, { skillsDir });
+  return rendered?.trim() || null;
+}

package/lib/ai/workspace-setup.js

@@ -1,6 +1,6 @@
 import { execFile as execFileCb } from 'child_process';
 import { promisify } from 'util';
-import { existsSync, mkdirSync, symlinkSync, unlinkSync, lstatSync } from 'fs';
+import { existsSync, mkdirSync } from 'fs';
 import path from 'path';
 import { getConfig } from '../config.js';
 
@@ -32,20 +32,25 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
   if (ghToken) env.GH_TOKEN = ghToken;
 
   const execOpts = { cwd: workspaceDir, env };
+  const log = [];
 
   // 1. Create workspace directory
   mkdirSync(workspaceDir, { recursive: true });
 
   // 2. Configure git to use GH_TOKEN for GitHub HTTPS URLs (mirrors setup-git.sh)
   if (ghToken) {
-    await run('gh', ['auth', 'setup-git'], execOpts);
+    const out = await run('gh', ['auth', 'setup-git'], execOpts);
+    if (out) log.push(out);
   }
 
   // 3. Clone if not already a git repo
   const hasGit = existsSync(path.join(workspaceDir, '.git'));
   if (!hasGit) {
     if (!repo) throw new Error('ensureWorkspaceRepo: repo is required for initial clone');
-    await run('git', ['clone', '--branch', branch || 'main', `https://github.com/${repo}`, '.'], execOpts);
+    if (!branch) throw new Error(`ensureWorkspaceRepo: branch is required (could not resolve default branch for ${repo})`);
+    const out = await run('git', ['clone', '--branch', branch, `https://github.com/${repo}`, '.'], execOpts);
+    log.push(`Cloned ${repo} (branch: ${branch})`);
+    if (out) log.push(out);
   }
 
   // 3. Git identity (only if not already configured)
@@ -61,6 +66,7 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
         const email = user.email || `${user.id}+${user.login}@users.noreply.github.com`;
         await run('git', ['config', 'user.name', name], execOpts);
         await run('git', ['config', 'user.email', email], execOpts);
+        log.push(`Git identity: ${name} <${email}>`);
       } catch (err) {
         console.error('[workspace-setup] Failed to set git identity:', err.message);
       }
@@ -68,7 +74,7 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
   }
 
   // 4. Feature branch checkout
-  if (!featureBranch) return;
+  if (!featureBranch) return log.join('\n');
 
   // Already on the right branch locally?
   try {
@@ -77,8 +83,11 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
     const current = await run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], execOpts);
     if (current !== featureBranch) {
       await run('git', ['checkout', featureBranch], execOpts);
+      log.push(`Checked out ${featureBranch}`);
+    } else {
+      log.push(`Already on ${featureBranch}`);
     }
-    return;
+    return log.join('\n');
   } catch {
     // Branch doesn't exist locally — check remote
   }
@@ -88,43 +97,18 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
     if (remoteCheck) {
       // Remote branch exists — checkout tracking it
       await run('git', ['checkout', '-B', featureBranch, `origin/${featureBranch}`], execOpts);
+      log.push(`Checked out ${featureBranch} (tracking origin)`);
     } else {
       // Create new branch and push
       await run('git', ['checkout', '-b', featureBranch], execOpts);
-      await run('git', ['push', '-u', 'origin', featureBranch], execOpts);
+      const pushOut = await run('git', ['push', '-u', 'origin', featureBranch], execOpts);
+      log.push(`Created and pushed ${featureBranch}`);
+      if (pushOut) log.push(pushOut);
     }
   } catch (err) {
     console.error('[workspace-setup] Feature branch error:', err.message);
     throw err;
   }
-}
-
-/**
- * Activate agent-job-secrets skill in the workspace when in agent chatMode.
- * Mirrors Docker setup.sh: ln -sfn ../library/agent-job-secrets skills/active/agent-job-secrets
- * Idempotent — skips if library skill doesn't exist.
- *
- * @param {string} workspaceDir - Absolute path to workspace (git repo root)
- * @param {string} chatMode - 'agent' or 'code'
- */
-export function ensureSkills(workspaceDir, chatMode) {
-  if (chatMode !== 'agent') return;
-
-  const librarySkill = path.join(workspaceDir, 'skills', 'library', 'agent-job-secrets');
-  if (!existsSync(librarySkill)) return;
-
-  const activeDir = path.join(workspaceDir, 'skills', 'active');
-  mkdirSync(activeDir, { recursive: true });
-
-  const link = path.join(activeDir, 'agent-job-secrets');
-
-  // ln -sfn: remove existing symlink/file before creating (force + no-deref)
-  try {
-    const stat = lstatSync(link);
-    if (stat) unlinkSync(link);
-  } catch {
-    // doesn't exist — fine
-  }
 
-  symlinkSync('../library/agent-job-secrets', link);
+  return log.join('\n');
 }

package/lib/channels/CLAUDE.md

@@ -17,7 +17,7 @@ Abstract interface for platform integrations. Methods:
 **Critical distinction**: Audio is preprocessed at the adapter layer. Images are passed through to the LLM.
 
 - **Images** (`message.photo`) → Downloaded, passed as `{ category: 'image', mimeType, data: Buffer }` attachment → LLM receives as vision content
-- **Audio** (`message.voice`/`message.audio`) → Transcribed via Whisper → merged into `text` field → **never passed as attachment**
+- **Audio** (`message.voice`/`message.audio`) → Transcribed via AssemblyAI → merged into `text` field → **never passed as attachment**
 - **Documents** (`message.document`) → Downloaded as `{ category: 'document', mimeType, data: Buffer }`
 
 ## Factory (index.js) — Lazy Singleton
@@ -26,7 +26,17 @@ Abstract interface for platform integrations. Methods:
 
 ## Telegram Adapter (telegram.js)
 
-- **Chat ID filtering**: `TELEGRAM_CHAT_ID` required. Messages from other chats are silently dropped. If not configured, all messages rejected.
-- **Verification flow**: If `TELEGRAM_VERIFICATION` env is set and user sends that code, bot responds with the chat ID (for initial setup).
+- **Authorization**: per-user via the `user_channels` table. Unverified chats only accept `/verify <code>`; all other messages are dropped. See `lib/db/user-channels.js` and `lib/channels/commands/verify.js`.
 - **Webhook auth**: Validates `x-telegram-bot-api-secret-token` header against `TELEGRAM_WEBHOOK_SECRET`.
-- **Streaming**: `supportsStreaming` returns `false` — sends complete responses only.
+- **Streaming**: `supportsStreaming` returns `false` — text + tool calls accumulate during streaming and are sent as complete messages once the turn ends. Progressive tool-call rendering (commit 740c734 / d9bf19a) inserts intermediate "→ used X" lines as tool calls land.
+
+## Slash Commands (`lib/channels/commands/`)
+
+Post-auth messages starting with `/` are dispatched here before reaching the LLM. Resolution chat.id → userId → activeThreadId happens in `api/index.js` `processChannelMessage`.
+
+| Command | Purpose | Source |
+|---------|---------|--------|
+| `/verify <code>` | Verify a Telegram account against a one-time code generated in the web UI (`/profile/telegram`). Code expires in 10 minutes. Sets `verifiedAt`. | `commands/verify.js` |
+| `/session` | List the user's recent chat threads (active thread marked) | `commands/session.js` |
+| `/session list` | Same as `/session` | `commands/session.js` |
+| `/session <id>` | Switch the user's `activeThreadId` so subsequent messages route to that chat | `commands/session.js` |

package/lib/channels/base.js

@@ -8,7 +8,10 @@ class ChannelAdapter {
    * Returns normalized message data or null if no action needed.
    *
    * @param {Request} request - Incoming HTTP request
-   * @returns {Promise<{ threadId: string, text: string, attachments: Array, metadata: object } | null>}
+   * @returns {Promise<{ channel: string, channelChatId: string, text: string, attachments: Array, metadata: object } | null>}
+   *
+   * `channelChatId` is the channel-native identifier (e.g. Telegram chat.id). It is
+   * NOT the DB chat/thread id — that is resolved downstream via user_channels.
    *
    * Attachments array (may be empty) — only non-text content that the LLM needs to see:
    *   { category: "image", mimeType: "image/png", data: Buffer }  — send to LLM as vision
@@ -39,8 +42,9 @@ class ChannelAdapter {
 
   /**
    * Send a complete (non-streaming) response back to the channel.
+   * `channelChatId` is the channel-native chat identifier.
    */
-  async sendResponse(threadId, text, metadata) {
+  async sendResponse(channelChatId, text, metadata) {
     throw new Error('Not implemented');
   }