pikiloom 0.4.26 → 0.4.27

package/dist/agent/skill-installer.js

@@ -1,38 +1,11 @@
-/**
- * Skill installer — wrapper around `npx skills` CLI.
- *
- * Skills are installed via the community-standard `npx skills add` command.
- * Global skills go to ~/.pikiloom/skills/, project skills to <workdir>/.pikiloom/skills/.
- *
- * The upstream CLI doesn't recognize `pikiloom` as an agent, so we install with
- * `--agent claude-code` (the driver pikiloom runs by default) and rely on
- * ~/.claude/skills → ~/.pikiloom/skills being symlinked to the same directory.
- */
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { STATE_DIR_NAME } from '../core/constants.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
 const GLOBAL_SKILLS_DIR = path.join(os.homedir(), STATE_DIR_NAME, 'skills');
 const INSTALL_TIMEOUT_MS = 60_000;
 const REMOVE_TIMEOUT_MS = 10_000;
-// ---------------------------------------------------------------------------
-// Install ledger — provenance for update detection
-//
-// `npx skills add` drops skill directories but records no source or version, so
-// there's nothing to diff a local install against a moving remote. We keep a
-// sidecar ledger next to the skills (one per scope: global beside
-// ~/.pikiloom/skills, project beside <workdir>/.pikiloom/skills) mapping each
-// installed collection (its GitHub source) to the default-branch commit SHA it
-// was pulled from. The dashboard reads the live remote HEAD, diffs it against
-// the ledger to surface "update available", then re-runs install to advance it.
-//
-// The file is a hidden sibling of the skill dirs; skill discovery and removal
-// only ever touch named sub-directories, so it's invisible to both.
-// ---------------------------------------------------------------------------
 const SKILL_LEDGER_FILE = '.pikiloom-skills-ledger.json';
 function ledgerPath(opts) {
     if (opts.global)
@@ -41,7 +14,6 @@ function ledgerPath(opts) {
         return path.join(opts.workdir, STATE_DIR_NAME, 'skills', SKILL_LEDGER_FILE);
     return null;
 }
-/** Normalize a source to a stable key: lowercase `owner/repo`, URL/.git stripped. */
 export function normalizeSkillSourceKey(source) {
     return String(source || '')
         .trim()
@@ -60,7 +32,7 @@ function readLedger(opts) {
             return { version: 1, entries: parsed.entries };
         }
     }
-    catch { /* missing or corrupt — treat as empty */ }
+    catch { }
     return { version: 1, entries: {} };
 }
 function writeLedger(ledger, opts) {
@@ -71,16 +43,14 @@ function writeLedger(ledger, opts) {
         fs.mkdirSync(path.dirname(p), { recursive: true });
         fs.writeFileSync(p, JSON.stringify(ledger, null, 2));
     }
-    catch { /* best effort — provenance is non-critical */ }
+    catch { }
 }
-/** Look up the recorded provenance for a source in the given scope. */
 export function getSkillLedgerEntry(source, opts) {
     const key = normalizeSkillSourceKey(source);
     if (!key)
         return null;
     return readLedger(opts).entries[key] || null;
 }
-/** Record (or refresh) the provenance for a source after a successful install/update. */
 export function recordSkillInstall(source, opts) {
     const key = normalizeSkillSourceKey(source);
     if (!key)
@@ -95,7 +65,6 @@ export function recordSkillInstall(source, opts) {
     };
     writeLedger(ledger, opts);
 }
-/** Drop a source's provenance — call when its skills are removed. */
 export function forgetSkillInstall(source, opts) {
     const key = normalizeSkillSourceKey(source);
     if (!key)
@@ -106,15 +75,6 @@ export function forgetSkillInstall(source, opts) {
         writeLedger(ledger, opts);
     }
 }
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * Make sure the global skills directory exists, and that the agent-specific
- * dirs that the upstream skills CLI writes to (`~/.claude/skills`,
- * `~/.agents/skills`) resolve back to it. This is what lets us install with
- * `--agent claude-code` and still read the results from `~/.pikiloom/skills`.
- */
 function ensureGlobalSkillsDir() {
     fs.mkdirSync(GLOBAL_SKILLS_DIR, { recursive: true });
     for (const linkDir of [
@@ -128,7 +88,6 @@ function ensureGlobalSkillsDir() {
                 if (real === fs.realpathSync(GLOBAL_SKILLS_DIR))
                     continue;
             }
-            // Existing dir/link doesn't match — leave it alone rather than destroy user data.
             continue;
         }
         catch {
@@ -136,7 +95,7 @@ function ensureGlobalSkillsDir() {
                 fs.mkdirSync(path.dirname(linkDir), { recursive: true });
                 fs.symlinkSync(GLOBAL_SKILLS_DIR, linkDir, 'dir');
             }
-            catch { /* best effort */ }
+            catch { }
         }
     }
 }
@@ -154,18 +113,9 @@ function runNpx(args, cwd, timeoutMs) {
                 stderr: stderr?.toString() || '',
             });
         });
-        // Prevent child from keeping parent alive
         child.unref?.();
     });
 }
-// ---------------------------------------------------------------------------
-// Install
-// ---------------------------------------------------------------------------
-/**
- * Install a skill from a source (GitHub owner/repo, URL, or local path).
- *
- * Uses `npx skills add <source>` with appropriate flags.
- */
 export async function installSkill(source, opts = {}) {
     const { global: isGlobal, skill, workdir } = opts;
     if (!isGlobal && !workdir) {
@@ -185,8 +135,6 @@ export async function installSkill(source, opts = {}) {
         const errorMsg = result.stderr.trim().split('\n').pop()?.trim() || 'installation failed';
         return { ok: false, error: errorMsg, output: result.stdout + result.stderr };
     }
-    // Record provenance so the dashboard can later detect remote updates. Scoped
-    // to where the skill landed; best-effort, never fails the install.
     recordSkillInstall(source, {
         global: isGlobal,
         workdir,
@@ -195,19 +143,11 @@ export async function installSkill(source, opts = {}) {
     });
     return { ok: true, output: result.stdout };
 }
-// ---------------------------------------------------------------------------
-// Remove
-// ---------------------------------------------------------------------------
-/**
- * Remove an installed skill by name.
- * Deletes the skill directory from the appropriate location.
- */
 export function removeSkill(skillName, opts = {}) {
     const { global: isGlobal, workdir } = opts;
     if (!isGlobal && !workdir) {
         return { ok: false, error: 'workdir is required for project-scoped skill removal' };
     }
-    // Security: prevent path traversal — skill name must be a plain directory name
     const sanitized = path.basename(skillName);
     if (!sanitized || sanitized === '.' || sanitized === '..' || sanitized !== skillName) {
         return { ok: false, error: 'invalid skill name' };
@@ -216,7 +156,6 @@ export function removeSkill(skillName, opts = {}) {
         ? GLOBAL_SKILLS_DIR
         : path.join(workdir, STATE_DIR_NAME, 'skills');
     const skillDir = path.join(parentDir, sanitized);
-    // Double-check the resolved path is inside the expected parent
     const realParent = path.resolve(parentDir);
     const realSkill = path.resolve(skillDir);
     if (!realSkill.startsWith(realParent + path.sep)) {
@@ -233,15 +172,9 @@ export function removeSkill(skillName, opts = {}) {
         return { ok: false, error: e?.message || 'removal failed' };
     }
 }
-// ---------------------------------------------------------------------------
-// List installed (enhanced)
-// ---------------------------------------------------------------------------
 export function getGlobalSkillsDir() {
     return GLOBAL_SKILLS_DIR;
 }
-// ---------------------------------------------------------------------------
-// Check for updates
-// ---------------------------------------------------------------------------
 export async function checkSkillUpdates(opts = {}) {
     const cwd = opts.global ? os.homedir() : (opts.workdir || process.cwd());
     const args = ['-y', 'skills', 'check'];

package/dist/agent/skills.js

@@ -1,6 +1,3 @@
-/**
- * Project skill discovery from .pikiloom/skills and .claude/commands.
- */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -28,7 +25,6 @@ function parseSkillMeta(content) {
         const dm = fm[1].match(/^description:\s*(.+)/m);
         if (dm)
             description = dm[1].trim();
-        // Parse mcp_requires as YAML list
         const mr = fm[1].match(/^mcp_requires:\s*\n((?:\s+-\s+.+\n?)+)/m);
         if (mr) {
             mcpRequires = mr[1]
@@ -105,11 +101,6 @@ function ensureDirSymlink(linkPath, targetDir) {
             const desiredReal = realPathOrNull(targetDir);
             if (currentTarget === desiredTarget || (currentReal && desiredReal && currentReal === desiredReal))
                 return;
-            // Symlink points elsewhere — including dangling legacy targets like the
-            // pre-rename `../.pikiclaw/skills`. `rmSync(recursive,force)` silently
-            // no-ops on a dangling symlink (it follows the link, sees the target is
-            // gone, treats it as already deleted) and leaves the link in place, which
-            // then trips EEXIST below. `unlinkSync` removes the link itself reliably.
             fs.unlinkSync(linkPath);
         }
         else {
@@ -122,9 +113,6 @@ function ensureDirSymlink(linkPath, targetDir) {
         fs.symlinkSync(desiredTarget, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
     }
     catch (err) {
-        // Tolerate a concurrent creator (the prod self-bootstrap and `npm run dev`
-        // can both initialize the same workdir) — if the link now resolves to the
-        // intended target, the race is benign; otherwise surface the real error.
         if (err?.code !== 'EEXIST' || fs.readlinkSync(linkPath) !== desiredTarget)
             throw err;
     }
@@ -169,33 +157,13 @@ export function getProjectSkillPaths(workdir, skillName) {
         claudeSkillFile: hasFile(claudeSkillFile) ? claudeSkillFile : null,
     };
 }
-// Matches the canonical prompt produced by `resolveSkillPrompt` (bot/commands)
-// and `resolveSkillFromPrompt` (dashboard/session-control). Both build the same
-// shape: `[Project directory: <wd>]\n\nRead the skill definition at \`<path>\`
-// and execute the instructions defined there.[ Additional context: <args>]`.
-//
-// Whitespace between the segments is tolerant (`\s+`) so the regex still
-// matches after the claude driver collapses interior `\s+` to single spaces
-// when surfacing user text in `getClaudeSessionMessages`.
 const SKILL_PROMPT_RE = /^\[Project directory: [^\]\n]+?\]\s+Read the skill definition at `([^`\n]+)` and execute the instructions defined there\.(?:\s+Additional context:\s+([\s\S]+?))?\s*$/;
-/**
- * Inverse of `resolveSkillPrompt`. When a stored user message matches the
- * canonical skill-execution expansion, return the original `/skillname [args]`
- * shorthand for display. Returns null when the text isn't a recognized skill
- * prompt — callers should fall back to the raw text.
- *
- * The expanded form is what the agent CLI actually consumed and what gets
- * persisted to its session log; this collapse exists purely so the dashboard
- * (and other display surfaces) can render the slash command the user typed.
- */
 export function collapseSkillPrompt(text) {
     if (!text)
         return null;
     const m = SKILL_PROMPT_RE.exec(text);
     if (!m)
         return null;
-    // Skill files are always at `<root>/<skillName>/SKILL.md`. Split on both
-    // `/` and `\` so Windows-generated paths (path.join) resolve correctly.
     const segments = m[1].split(/[/\\]/).filter(Boolean);
     if (segments.length < 2 || segments[segments.length - 1] !== 'SKILL.md')
         return null;
@@ -206,9 +174,6 @@ export function collapseSkillPrompt(text) {
     return args ? `/${name} ${args}` : `/${name}`;
 }
 const GLOBAL_SKILLS_ROOT = path.join(os.homedir(), STATE_DIR_NAME, 'skills');
-// Per-file cache of parsed SKILL.md metadata, keyed by file mtime. listSkills runs
-// on every skills-menu render (IM + dashboard); without this it re-read and
-// re-regex-parsed every SKILL.md each time. A changed skill re-parses just itself.
 const skillMetaCache = new Map();
 function discoverSkillsFromDir(dir, scope, seen) {
     const skills = [];
@@ -251,24 +216,16 @@ function discoverSkillsFromDir(dir, scope, seen) {
     }
     return skills;
 }
-/**
- * List all skills — project-scoped (workdir) first, then global (~/.pikiloom/skills/).
- * Project skills with the same name shadow global ones.
- */
 export function listSkills(workdir) {
     const seen = new Set();
     const { canonicalRoot, legacyRoots } = resolveProjectSkillRoots(workdir);
-    // Project skills take precedence. Also scan the pre-rename `.pikiclaw/skills`
-    // dir so repos that committed project skills before the rename keep working.
     const projectSkills = [
         ...discoverSkillsFromDir(canonicalRoot, 'project', seen),
         ...legacyRoots.flatMap(root => discoverSkillsFromDir(root, 'project', seen)),
     ];
-    // Global skills fill in the rest
     const globalSkills = discoverSkillsFromDir(GLOBAL_SKILLS_ROOT, 'global', seen);
     return { skills: [...projectSkills, ...globalSkills], workdir };
 }
-/** Return the global skills root directory path. */
 export function getGlobalSkillsRoot() {
     return GLOBAL_SKILLS_ROOT;
 }

package/dist/agent/stream.js

@@ -1,6 +1,3 @@
-/**
- * CLI spawn framework, stream orchestration, agent detection, and driver delegation.
- */
 import { execSync, spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import fs from 'node:fs';
@@ -12,12 +9,9 @@ import { awaitAgentUpdateIdle } from './auto-update.js';
 import { getDriver, allDrivers, getAcceptedProviderKinds, hasDriver } from './driver.js';
 import { resolveAgentInjection, getActiveProfile, getActiveProfileId, getProvider, updateProfile, listProfiles, } from '../model/index.js';
 import { Q, agentLog, agentWarn, agentError, joinErrorMessages, normalizeErrorMessage, buildStreamPreviewMeta, computeContext, shortValue, isPendingSessionId, dedupeStrings, normalizeStreamPreviewPlan, } from './utils.js';
-import { saveSessionRecord, setSessionRunState, applySessionRunResult, ensureSessionWorkspace, importFilesIntoWorkspace, syncManagedSessionIdentity, summarizePromptTitle, recordFork, } from './session.js';
+import { saveSessionRecord, setSessionRunState, applySessionRunResult, ensureSessionWorkspace, importFilesIntoWorkspace, syncManagedSessionIdentity, summarizePromptTitle, recordFork, resolveCanonicalSessionId, } from './session.js';
 import { clearAwaitResume } from './await-resume.js';
 import { collapseSkillPrompt } from './skills.js';
-// ---------------------------------------------------------------------------
-// Private helpers
-// ---------------------------------------------------------------------------
 function trimSessionText(value, max = 24_000) {
     const text = typeof value === 'string' ? value.trim() : '';
     if (!text)
@@ -26,14 +20,6 @@ function trimSessionText(value, max = 24_000) {
         return text;
     return `${text.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
 }
-/**
- * Spot known browser-MCP failure signatures inside an agent stdout line so the
- * supervisor can force-restart Chrome before the next turn. Both patterns are
- * narrow on purpose: `Frame has been detached` is playwright-specific; the
- * `Connection closed` MCP error only triggers when the same line names the
- * `pikiloom-browser` server, so failures on other MCP servers do not nuke the
- * managed browser. The supervisor itself debounces, so this can fire freely.
- */
 export function _detectBrowserMcpFailure(rawLine) {
     if (!rawLine)
         return null;
@@ -44,9 +30,6 @@ export function _detectBrowserMcpFailure(rawLine) {
     }
     return null;
 }
-// ---------------------------------------------------------------------------
-// Agent detection (private helpers and cache)
-// ---------------------------------------------------------------------------
 const AGENT_DETECT_TTL_MS = AGENT_DETECT_TIMEOUTS.detectTtl;
 const AGENT_VERSION_TTL_MS = AGENT_DETECT_TIMEOUTS.versionTtl;
 const AGENT_VERSION_TIMEOUT_MS = AGENT_DETECT_TIMEOUTS.versionCommand;
@@ -114,7 +97,6 @@ function readAgentVersion(binPath, timeoutMs) {
         return null;
     }
 }
-// Agent detection (used by all drivers)
 export function detectAgentBin(cmd, agent, options = {}) {
     const cacheKey = `${agent}:${cmd}`;
     const now = Date.now();
@@ -155,23 +137,6 @@ export function detectAgentBin(cmd, agent, options = {}) {
 export function listAgents(options = {}) {
     return { agents: allDrivers().map(d => detectAgentBin(d.cmd, d.id, options)) };
 }
-/**
- * Resolve the *effective* default agent for new conversations.
- *
- * The stored value is only a *preference* — a new conversation can run only an
- * agent whose CLI is actually installed. So when the preference's CLI isn't
- * installed, we clamp to the first installed agent (in driver-registration
- * order: claude → codex → gemini → hermes) instead of surfacing an uninstalled
- * default the user can't run. When the preference *is* installed it always
- * wins, so machines with the historical 'codex' default are unaffected. When
- * nothing is installed we keep the prior behaviour (honour a valid preference,
- * else 'codex') so the result is always defined.
- *
- * Resolution is derived, never persisted: if the user later installs their
- * preferred agent, the original preference is honoured again automatically.
- * `agents` is injected (defaults to live detection) so the resolution is a pure
- * function of (preference, install-state) and trivially testable.
- */
 export function resolveDefaultAgent(preferred, agents = listAgents().agents) {
     const want = typeof preferred === 'string' ? preferred.trim().toLowerCase() : '';
     const wantValid = !!want && hasDriver(want);
@@ -182,9 +147,6 @@ export function resolveDefaultAgent(preferred, agents = listAgents().agents) {
         return installed[0];
     return wantValid ? want : 'codex';
 }
-// ---------------------------------------------------------------------------
-// Shared CLI spawn framework (used by driver-claude.ts, driver-gemini.ts)
-// ---------------------------------------------------------------------------
 export async function run(cmd, opts, parseLine, parseStderrLine) {
     const start = Date.now();
     const deadline = start + opts.timeout * 1000;
@@ -192,10 +154,6 @@ export async function run(cmd, opts, parseLine, parseStderrLine) {
     let lineCount = 0;
     let timedOut = false;
     let interrupted = false;
-    // BYOK: seed contextWindow from the provider-cached value so the live
-    // preview percent uses the real denominator (e.g. 1M for DeepSeek v4 Pro
-    // via OpenRouter) instead of whatever the CLI happens to report later.
-    // Parsers gate their cc/codex-advertised updates on `s.byokContextWindow`.
     const byokWindow = opts.byokContextWindow && opts.byokContextWindow > 0
         ? opts.byokContextWindow
         : null;
@@ -205,8 +163,6 @@ export async function run(cmd, opts, parseLine, parseStderrLine) {
         model: opts.model, thinkingEffort: opts.thinkingEffort, errors: null,
         inputTokens: null, outputTokens: null, cachedInputTokens: null,
         cacheCreationInputTokens: null,
-        // Output tokens from this turn's finished LLM calls — folded in by parsers
-        // when a new call resets the per-call counter (claude message_start).
         turnOutputTokensBase: 0,
         contextWindow: byokWindow,
         byokContextWindow: byokWindow,
@@ -218,14 +174,8 @@ export async function run(cmd, opts, parseLine, parseStderrLine) {
         claudeToolsById: new Map(),
         seenClaudeToolIds: new Set(),
         geminiToolsById: new Map(),
-        // Claude-only: sub-agent invocations from the Task tool. Other drivers leave it empty.
         subAgents: new Map(),
-        // Image blocks collected during the stream (assistant images, MCP tool
-        // results, …). Surfaced on the StreamResult so IM channels can dispatch
-        // them at end-of-turn without re-reading the session file.
         imageBlocks: [],
-        // Wired to opts.onSessionId so parsers can broadcast id changes the instant
-        // the CLI surfaces them (see emitSessionIdUpdate in agent/utils.ts).
         _emitSessionId: opts.onSessionId ?? null,
     };
     const shellCmd = cmd.map(Q).join(' ');
@@ -243,9 +193,6 @@ export async function run(cmd, opts, parseLine, parseStderrLine) {
     });
     agentLog(`[spawn] pid=${proc.pid}`);
     proc.stdin?.on('error', (e) => {
-        // Some CLIs can exit after producing all output before we finish writing
-        // stdin. Treat EPIPE as a normal early-close race; the exit code/stdout
-        // still determine the stream result.
         if (e?.code !== 'EPIPE')
             agentWarn(`[stdin] write failed: ${e?.message || e}`);
     });
@@ -370,38 +317,26 @@ export async function run(cmd, opts, parseLine, parseStderrLine) {
         assistantBlocks: s.imageBlocks.length ? [...s.imageBlocks] : undefined,
     };
 }
-// ---------------------------------------------------------------------------
-// Stream orchestration
-// ---------------------------------------------------------------------------
 function prepareStreamOpts(opts) {
-    // For display fields (title / lastQuestion / lastMessageText) prefer the
-    // `/skillname` shorthand the user typed over the long expansion we
-    // synthesized for the agent — the expanded form is what the CLI consumes,
-    // but it shouldn't leak into session list previews or sidebar tabs.
     const displayPrompt = collapseSkillPrompt(opts.prompt) ?? opts.prompt;
-    const session = ensureSessionWorkspace({ agent: opts.agent, workdir: opts.workdir, sessionId: opts.sessionId, title: displayPrompt });
+    const resolvedInboundSessionId = opts.sessionId
+        ? resolveCanonicalSessionId(opts.workdir, opts.agent, opts.sessionId)
+        : opts.sessionId;
+    const session = ensureSessionWorkspace({ agent: opts.agent, workdir: opts.workdir, sessionId: resolvedInboundSessionId, title: displayPrompt });
     const importedFiles = importFilesIntoWorkspace(session.workspacePath, opts.attachments || []);
     const attachmentRelPaths = dedupeStrings([...session.record.stagedFiles, ...importedFiles]);
-    // Capture staged files for MCP bridge before clearing
     const stagedFiles = [...session.record.stagedFiles];
     session.record.stagedFiles = [];
-    // Remember this turn's attachments so dashboard fallbacks (called while the
-    // agent CLI hasn't yet flushed the user event to its native session file)
-    // can still render the user's image bubble. Cleared/overwritten at the
-    // start of the NEXT turn — always reflects the turn currently in flight.
     session.record.lastUserAttachments = [...attachmentRelPaths];
     if (!session.record.title)
         session.record.title = summarizePromptTitle(displayPrompt) || null;
     session.record.lastQuestion = shortValue(displayPrompt, 500);
     session.record.lastMessageText = shortValue(displayPrompt, 500);
     setSessionRunState(session.record, 'running', null);
-    // A turn starting clears any "waiting on background work" marker the previous
-    // turn parked — the session is plainly running again, not waiting.
     if (session.sessionId)
         clearAwaitResume(opts.workdir, opts.agent, session.sessionId);
     saveSessionRecord(opts.workdir, session.record);
     const attachmentPaths = attachmentRelPaths.map(relPath => path.join(session.workspacePath, relPath));
-    // For pending sessions, pass null sessionId to the CLI so it creates a new session
     const effectiveSessionId = isPendingSessionId(session.sessionId) ? null : session.sessionId;
     return {
         session,
@@ -431,19 +366,12 @@ function finalizeStreamResult(result, workdir, prompt, session, workflowEnabled)
     session.record.model = result.model || session.record.model;
     if (result.thinkingEffort)
         session.record.thinkingEffort = result.thinkingEffort;
-    // Remember whether this turn ran with Workflow on so the synthetic `ultra`
-    // rung re-folds for display after the live stream ends and on resume — the
-    // stored `thinkingEffort` stays the concrete rung (e.g. `max`). `undefined`
-    // (driver invoked outside the bot) leaves the prior value untouched.
     if (workflowEnabled !== undefined)
         session.record.workflowEnabled = workflowEnabled;
-    // Capture the BYOK Profile that was in effect for this run so a future
-    // `session.switch` can re-bind it (null = native CLI auth).
     try {
         session.record.profileId = getActiveProfileId(session.record.agent);
     }
     catch {
-        /* model layer not initialised in tests — leave profileId untouched */
     }
     const displayPrompt = collapseSkillPrompt(prompt) ?? prompt;
     if (!session.record.title)
@@ -477,7 +405,6 @@ export async function doStream(opts) {
             codexCumulative: null, error: message, stopReason: null, incomplete: true, activity: null, plan: null,
         };
     }
-    // Start MCP bridge for IM tools (when sendFile is available) and/or supplemental servers (browser, etc.)
     let bridge = null;
     try {
         const { startMcpBridge, redactMcpConfigForLog } = await import('./mcp/bridge.js');
@@ -515,9 +442,6 @@ export async function doStream(opts) {
     catch (e) {
         agentWarn(`[mcp] bridge start failed: ${e.message} — proceeding without MCP`);
     }
-    // Apply BYOK injection (Provider/Profile from the model layer): merges env
-    // vars into prepared.extraEnv, overrides the per-agent model field, and
-    // hands argvAppend to drivers that consume it (Hermes via opts.extraEnv → its own argv builder).
     try {
         const injection = await resolveAgentInjection(prepared.agent);
         if (injection) {
@@ -548,9 +472,6 @@ export async function doStream(opts) {
             }
             agentLog(`[byok] ${injection.detail}`);
         }
-        // resolveAgentEffort (runtime-config) reads only the top-level hermesReasoningEffort
-        // field and cannot see the effort stored inside models.profiles[].effort. Override
-        // thinkingEffort here so the Profile's effort wins over the config default.
         const activeProfile = getActiveProfile(prepared.agent);
         if (activeProfile?.effort) {
             prepared.thinkingEffort = activeProfile.effort;
@@ -559,13 +480,6 @@ export async function doStream(opts) {
     catch (e) {
         agentWarn(`[byok] failed to apply Profile injection: ${e?.message || e}`);
     }
-    // In-memory-first: stamp the turn's resolved reasoning rung + Workflow opt-in
-    // onto the centralized index NOW — before the agent CLI has flushed its own
-    // session file — so the session list/composer reflect the user's pick during
-    // the very first turn instead of only after finalizeStreamResult. The managed
-    // record is the single source of truth for this metadata and links to the
-    // native agent-session by id on promotion; finalize re-stamps it (plus the
-    // actual model) authoritatively at turn end.
     try {
         if (prepared.thinkingEffort) {
             session.record.thinkingEffort = prepared.thinkingEffort.trim().toLowerCase() || session.record.thinkingEffort;
@@ -583,18 +497,9 @@ export async function doStream(opts) {
         if (opts.forkOf && !driver.capabilities?.fork) {
             throw new Error(`Agent ${prepared.agent} does not support fork`);
         }
-        // A background agent-CLI auto-update (`npm install -g` / `brew upgrade`, by
-        // this process OR the `npx pikiloom@latest` self-bootstrap) briefly removes
-        // the bin while it relinks; exec'ing into that window fails with exit 127
-        // "command not found". Wait out any in-flight reinstall of THIS agent before
-        // dispatching to the driver — this is the one chokepoint every agent turn
-        // (claude -p, claude TUI, codex app-server, gemini) passes through. No-op
-        // when nothing is updating.
         await awaitAgentUpdateIdle(prepared.agent, AGENT_UPDATE_TIMEOUTS.spawnWait);
         const result = await driver.doStream(prepared);
         const finalized = finalizeStreamResult(result, opts.workdir, opts.prompt, session, opts.claudeWorkflowEnabled);
-        // Once the child has its real session ID, link the lineage. We do this
-        // after finalize so the child record is persisted with its native ID.
         if (opts.forkOf && finalized.sessionId) {
             try {
                 recordFork(opts.workdir, {
@@ -651,9 +556,6 @@ export async function doStream(opts) {
         }
     }
 }
-// ---------------------------------------------------------------------------
-// Driver delegation
-// ---------------------------------------------------------------------------
 export function getSessions(opts) {
     const workdir = path.resolve(opts.workdir);
     agentLog(`[sessions] request agent=${opts.agent} workdir=${workdir} limit=${opts.limit ?? 'all'}`);
@@ -671,37 +573,11 @@ export function getSessionMessages(opts) {
 export function listModels(agent, opts = {}) {
     return getDriver(agent).listModels(opts);
 }
-/**
- * Detect a Provider whose baseURL is on the local machine (Ollama / mlx-lm
- * connected via `/api/local-models/connect`). Used only to bucket the entry
- * into the `'local'` group in the unified picker — runtime behaviour is
- * unchanged whether or not the baseURL is loopback.
- */
 function isLocalProviderBaseURL(baseURL) {
     return /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::|\/|$)/i.test(baseURL);
 }
-/**
- * Resolve the model list a UI surface should show for `agent`.
- *
- * Returns a *union* of:
- *   1. The agent CLI's native model catalogue (no Profile required), tagged
- *      `group: 'native'`.
- *   2. Every Profile whose provider kind appears in the driver's
- *      `acceptedProviderKinds`, tagged `group: 'cloud'` (remote BYOK) or
- *      `group: 'local'` (loopback baseURL — Ollama / mlx-lm).
- *
- * The previous behaviour — filter to the active Profile's provider — meant
- * users could not switch *across* providers from the IM picker without first
- * unbinding through the dashboard. The unified list removes that step so
- * `/models` is a one-screen pick.
- *
- * Callers that need the strictly-native list (e.g. the dashboard agent card's
- * "Native" branch) should call `driver.listModels()` directly — this function
- * is for the unified picker.
- */
 export async function resolveAgentModels(agent, opts = {}) {
     const driver = getDriver(agent);
-    // 1. Native — agent CLI's built-in catalogue.
     let nativeResult;
     try {
         nativeResult = await driver.listModels(opts);
@@ -714,10 +590,6 @@ export async function resolveAgentModels(agent, opts = {}) {
         alias: m.alias,
         group: 'native',
     }));
-    // 2. BYOK Profiles compatible with this driver — grouped into cloud vs local
-    //    by baseURL. We never call the provider's /models endpoint here: that
-    //    list can run into the hundreds for OpenRouter and would drown the
-    //    picker. Profiles ARE the curated middle layer.
     const acceptedKinds = new Set(getAcceptedProviderKinds(agent));
     const cloud = [];
     const local = [];
@@ -754,25 +626,10 @@ export async function resolveAgentModels(agent, opts = {}) {
 export function getUsage(opts) {
     return getDriver(opts.agent).getUsage(opts);
 }
-/**
- * If the user has a BYOK Profile bound to `agent`, return its raw modelId
- * (e.g. "deepseek/deepseek-v4-flash"). Returns null when no profile is bound.
- * Used by display paths that need to show the profile's model rather than the
- * pikiloom user-config model (which may be stale or unrelated to the active profile).
- */
 export function getAgentBoundModelId(agent) {
     const profile = getActiveProfile(agent);
     return profile?.modelId ?? null;
 }
-/**
- * Persist a model id to the active BYOK Profile for `agent`. Returns true when
- * the Profile was updated (caller should skip writing the legacy
- * `<agent>Model` user-config field), false when no Profile is bound.
- *
- * Hermes uses this as the *primary* persistence path because `hermes acp` does
- * not support runtime model switching via CLI flags — the only way to change
- * the model is the Profile (which the driver passes to ACP `session/set_model`).
- */
 export function setAgentBoundModelId(agent, modelId) {
     const profile = getActiveProfile(agent);
     if (!profile)

package/dist/agent/types.js

@@ -1,13 +1 @@
-/**
- * types.ts — Shared type definitions for the agent layer.
- *
- * All type aliases, interfaces, and type-level constants used across the
- * agent subsystem (drivers, session management, streaming, listing, usage)
- * are centralised here so that consumers can import types without pulling
- * in runtime code.
- */
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/** Set of image file extensions recognised for workspace file handling. */
 export const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);