@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/subagents.js

@@ -1,11 +1,3 @@
-/**
- * Subagent management -- discovery, installation, and format conversion.
- *
- * Subagents are named agent definitions in ~/.agents/subagents/, each a directory
- * with an agent.md file (frontmatter + instructions). This module discovers them,
- * transforms them into agent-native formats (Claude .mdc, OpenClaw YAML),
- * and syncs them into version homes.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -14,22 +6,13 @@ import { getSubagentsDir, getUserSubagentsDir, getTrashSubagentsDir } from './st
 import { listInstalledVersions, getVersionHomePath } from './installations/versions.js';
 import { safeJoin } from './paths.js';
 import { subagentTarget, writeSubagentToHome, listInstalledSubagentNames, listInstalledSubagentsRich, removeSubagentFromHome, trashSubagentFromHome, copyDirWithRename, } from './subagents-registry.js';
-/**
- * Parse AGENT.md frontmatter to extract subagent metadata
- */
 export function parseSubagentFrontmatter(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
     }
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
-        // Split on CRLF or LF: git checks text files out with CRLF on Windows
-        // (core.autocrlf), so a plain split('\n') leaves a trailing '\r' on every
-        // line and the frontmatter fence `'---\r' !== '---'` never matches —
-        // silently dropping the subagent from discovery so it can never be
-        // installed or reconciled (PHNX-3187).
         const lines = content.split(/\r?\n/);
-        // Check for YAML frontmatter
         if (lines[0] === '---') {
             const endIndex = lines.slice(1).findIndex((l) => l === '---');
             if (endIndex > 0) {
@@ -49,17 +32,12 @@ export function parseSubagentFrontmatter(filePath) {
         return null;
     }
 }
-/**
- * Get the body content of AGENT.md (everything after frontmatter)
- */
 export function getSubagentBody(filePath) {
     if (!fs.existsSync(filePath)) {
         return '';
     }
     const content = fs.readFileSync(filePath, 'utf-8');
-    // CRLF-robust for the same reason as parseSubagentFrontmatter (PHNX-3187).
     const lines = content.split(/\r?\n/);
-    // Skip YAML frontmatter
     if (lines[0] === '---') {
         const endIndex = lines.slice(1).findIndex((l) => l === '---');
         if (endIndex > 0) {
@@ -68,10 +46,6 @@ export function getSubagentBody(filePath) {
     }
     return content;
 }
-/**
- * Discover subagents from a repository
- * Looks for subagents/{name}/AGENT.md
- */
 export function discoverSubagentsFromRepo(repoPath) {
     const subagents = [];
     const subagentsDir = path.join(repoPath, 'subagents');
@@ -84,7 +58,6 @@ export function discoverSubagentsFromRepo(repoPath) {
             continue;
         const agentMd = path.join(dirPath, 'AGENT.md');
         if (!fs.existsSync(agentMd)) {
-            // Skip directories without AGENT.md
             continue;
         }
         const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -92,12 +65,11 @@ export function discoverSubagentsFromRepo(repoPath) {
             console.warn(`Warning: ${agentMd} has invalid frontmatter, skipping`);
             continue;
         }
-        // Collect all .md files in the directory
         const files = fs.readdirSync(dirPath)
             .filter(f => f.endsWith('.md'))
             .sort();
         subagents.push({
-            name: dir, // Use directory name as canonical name
+            name: dir,
             path: dirPath,
             files,
             agentMd,
@@ -106,13 +78,9 @@ export function discoverSubagentsFromRepo(repoPath) {
     }
     return subagents;
 }
-/**
- * List installed subagents from ~/.agents/subagents/
- */
 export function listInstalledSubagents() {
     const seen = new Set();
     const subagents = [];
-    // User dir first (wins on name collision), then system
     for (const subagentsDir of [getUserSubagentsDir(), getSubagentsDir()]) {
         if (!fs.existsSync(subagentsDir))
             continue;
@@ -142,11 +110,7 @@ export function listInstalledSubagents() {
     }
     return subagents;
 }
-/**
- * Get a specific installed subagent
- */
 export function getInstalledSubagent(name) {
-    // Check user dir first, then system
     for (const subagentsDir of [getUserSubagentsDir(), getSubagentsDir()]) {
         const dirPath = path.join(subagentsDir, name);
         if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
@@ -162,22 +126,16 @@ export function getInstalledSubagent(name) {
     }
     return null;
 }
-/**
- * Install a subagent centrally to ~/.agents/subagents/{name}/
- */
 export function installSubagentCentrally(sourcePath, name) {
     const subagentsDir = getUserSubagentsDir();
     const targetDir = safeJoin(subagentsDir, name);
     try {
-        // Ensure subagents directory exists
         if (!fs.existsSync(subagentsDir)) {
             fs.mkdirSync(subagentsDir, { recursive: true });
         }
-        // Remove existing if present
         if (fs.existsSync(targetDir)) {
             fs.rmSync(targetDir, { recursive: true });
         }
-        // Copy entire directory
         fs.cpSync(sourcePath, targetDir, { recursive: true });
         return { success: true };
     }
@@ -185,9 +143,6 @@ export function installSubagentCentrally(sourcePath, name) {
         return { success: false, error: String(err) };
     }
 }
-/**
- * Remove an installed subagent
- */
 export function removeSubagent(name) {
     for (const subagentsDir of [getUserSubagentsDir(), getSubagentsDir()]) {
         const candidate = safeJoin(subagentsDir, name);
@@ -203,10 +158,6 @@ export function removeSubagent(name) {
     }
     return { success: false, error: `Subagent '${name}' not found` };
 }
-/**
- * Transform a subagent directory into a single .md file for Claude
- * Combines AGENT.md frontmatter + body with other files as sections
- */
 export function transformSubagentForClaude(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -214,7 +165,6 @@ export function transformSubagentForClaude(subagentDir) {
     if (!frontmatter) {
         throw new Error(`Invalid AGENT.md in ${subagentDir}`);
     }
-    // Build the frontmatter section
     const frontmatterYaml = yaml.stringify({
         name: frontmatter.name,
         description: frontmatter.description,
@@ -222,7 +172,6 @@ export function transformSubagentForClaude(subagentDir) {
         ...(frontmatter.color && { color: frontmatter.color }),
     }).trim();
     let result = `---\n${frontmatterYaml}\n---\n\n${body}`;
-    // Append other .md files as sections
     const files = fs.readdirSync(subagentDir)
         .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
         .sort();
@@ -230,20 +179,11 @@ export function transformSubagentForClaude(subagentDir) {
         const filePath = path.join(subagentDir, file);
         const content = fs.readFileSync(filePath, 'utf-8').trim();
         const sectionName = file.replace('.md', '');
-        // Convert filename to title case (SOUL.md -> Soul)
         const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
         result += `\n\n## ${title}\n\n${content}`;
     }
     return result;
 }
-/**
- * Transform a subagent into a Factory AI Droid "custom droid" .md file.
- *
- * Mirrors transformSubagentForClaude (flatten frontmatter + body + appended
- * .md sections), but emits only frontmatter keys Factory recognizes
- * (name, description, model). Factory has no `color` field, so it is dropped.
- * See https://docs.factory.ai/cli/configuration/custom-droids.
- */
 export function transformSubagentForDroid(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -269,41 +209,12 @@ export function transformSubagentForDroid(subagentDir) {
     }
     return result;
 }
-/**
- * Transform a subagent into a GitHub Copilot CLI custom agent `.agent.md` file.
- *
- * Copilot custom agents are Markdown profiles with YAML frontmatter stored in
- * `~/.copilot/agents/` (user) or `.github/agents/` (project). The file name
- * ends in `.agent.md` and the frontmatter carries `name`, `description`, and
- * optionally `model` and `tools`. The emitted body is identical to Factory
- * Droid's custom-droid format (flatten frontmatter + body + appended .md
- * sections, `color` dropped), so this is an alias of transformSubagentForDroid.
- * See GitHub docs for custom agents.
- */
 export function transformSubagentForCopilot(subagentDir) {
     return transformSubagentForDroid(subagentDir);
 }
-/**
- * Transform a subagent into a Cursor CLI custom subagent `.md` file.
- *
- * Cursor loads subagents from `.cursor/agents/*.md` (project) or
- * `~/.cursor/agents/*.md` (user) — Markdown with YAML frontmatter
- * (name, description, model; also readonly/is_background, which our
- * frontmatter schema doesn't carry). Cursor has no `color` field, so this is
- * an alias of transformSubagentForDroid, same as Copilot.
- * See https://cursor.com/docs/subagents.
- */
 export function transformSubagentForCursor(subagentDir) {
     return transformSubagentForDroid(subagentDir);
 }
-/**
- * Transform a subagent into Antigravity's custom-agent markdown shape.
- *
- * Antigravity exposes custom agents as Markdown files with YAML frontmatter,
- * close to Gemini CLI subagents. Keep portable frontmatter fields and flatten
- * sibling markdown files into the prompt body like the other markdown-backed
- * agents.
- */
 export function transformSubagentForAntigravity(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -329,14 +240,6 @@ export function transformSubagentForAntigravity(subagentDir) {
     }
     return `${result.trim()}\n`;
 }
-/**
- * Transform a subagent into an OpenCode agent markdown file.
- *
- * OpenCode loads agents from ~/.config/opencode/agents/*.md (global) with
- * YAML frontmatter (description required; mode: subagent for invocable
- * subagents) and a prompt body. File stem becomes the agent name.
- * https://opencode.ai/docs/agents/
- */
 export function transformSubagentForOpenCode(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -362,14 +265,6 @@ export function transformSubagentForOpenCode(subagentDir) {
     }
     return `---\n${yaml.stringify(fm).trim()}\n---\n\n${systemPrompt}\n`;
 }
-/**
- * Transform a subagent into a Codex custom-agent TOML file.
- *
- * Codex loads standalone TOML under ~/.codex/agents/*.toml. Required fields:
- * name, description, developer_instructions. Optional model maps from our
- * frontmatter when present.
- * https://developers.openai.com/codex/subagents (custom agents section)
- */
 export function transformSubagentForCodex(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -377,8 +272,6 @@ export function transformSubagentForCodex(subagentDir) {
         throw new Error(`Invalid AGENT.md in ${subagentDir}`);
     }
     const instructions = flattenSubagentInstructions(subagentDir);
-    // TOML multi-line basic strings still process backslash escapes, so a literal
-    // backslash (a Windows path, a regex) must be doubled before """ is escaped.
     const safeInstructions = instructions.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""');
     const safeName = frontmatter.name.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     const safeDesc = frontmatter.description.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
@@ -404,16 +297,6 @@ function flattenSubagentInstructions(subagentDir) {
     }
     return instructions;
 }
-/**
- * Transform a subagent into a Goose recipe YAML file.
- *
- * Goose has no dedicated subagent file format — a named subagent IS a recipe.
- * Goose resolves named agents from `~/.config/goose/agents/<name>.yaml` (global)
- * and delegates to them by name in autonomous mode. The recipe schema mirrors the
- * one agents-cli already emits for Goose workflow recipes (`writeGooseSubrecipe`):
- * `version`, `title`, `description`, `instructions`, `prompt`, plus an optional
- * `settings.goose_model`. See goose-docs.ai context-engineering/subagents.
- */
 export function transformSubagentForGoose(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
@@ -443,10 +326,6 @@ export function transformSubagentForGoose(subagentDir) {
     }
     return yaml.stringify(recipe);
 }
-/**
- * Sync a subagent to an OpenClaw workspace
- * Copies full directory, renames AGENT.md to AGENTS.md
- */
 export function syncSubagentToOpenclaw(subagentDir, targetDir) {
     try {
         copyDirWithRename(subagentDir, targetDir, { 'AGENT.md': 'AGENTS.md' });
@@ -456,9 +335,6 @@ export function syncSubagentToOpenclaw(subagentDir, targetDir) {
         return { success: false, error: String(err) };
     }
 }
-/**
- * Install a subagent to a specific agent's home
- */
 export function installSubagentToAgent(subagentDir, subagentName, agent, agentHome) {
     if (!subagentTarget(agent)) {
         return { success: false, error: `Agent '${agent}' does not support subagents` };
@@ -471,16 +347,9 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
         return { success: false, error: String(err) };
     }
 }
-/**
- * Remove a subagent from a specific agent's home
- */
 export function removeSubagentFromAgent(subagentName, agent, agentHome) {
-    // No-op success for agents without a registry entry, matching prior behavior.
     return removeSubagentFromHome(agent, agentHome, subagentName);
 }
-/**
- * Check if subagent content matches between source and installed
- */
 export function subagentContentMatches(installedDir, sourceDir) {
     if (!fs.existsSync(installedDir) || !fs.existsSync(sourceDir)) {
         return false;
@@ -502,26 +371,11 @@ export function subagentContentMatches(installedDir, sourceDir) {
     }
     return true;
 }
-// SUBAGENT_CAPABLE_AGENTS removed — use `capableAgents('subagents')` from
-// lib/capabilities.ts. The capability matrix on AgentConfig is the single
-// source of truth.
-/**
- * List subagents installed to a specific agent's home.
- *
- * Layout (target dir, file/dir shape, metadata reader) is declared once per
- * agent in the subagent registry; this is a thin wrapper over the generic
- * enumerator so a new agent needs no arm here -- just a registry entry.
- */
 export function listSubagentsForAgent(agentId, home) {
     return listInstalledSubagentsRich(agentId, home);
 }
-/**
- * Compare a version home's subagents against discovered subagents.
- * Returns orphan subagent names.
- */
 export function diffVersionSubagents(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
-    // Get all discovered subagent names
     const discovered = new Set();
     for (const dir of [getSubagentsDir(), getUserSubagentsDir()]) {
         if (fs.existsSync(dir)) {
@@ -532,14 +386,9 @@ export function diffVersionSubagents(agent, version) {
             }
         }
     }
-    // Anything installed in the version home that isn't a discovered subagent is
-    // an orphan. Installed enumeration is registry-driven (per-agent layout).
     const orphans = listInstalledSubagentNames(agent, versionHome).filter((name) => !discovered.has(name));
     return { agent, version, orphans: orphans.sort() };
 }
-/**
- * Iterate all (agent, version) pairs that support subagents and are installed.
- */
 export function iterSubagentsCapableVersions(filter) {
     const pairs = [];
     const agents = filter?.agent ? [filter.agent] : capableAgents('subagents');
@@ -555,15 +404,9 @@ export function iterSubagentsCapableVersions(filter) {
     }
     return pairs;
 }
-/**
- * Remove a single subagent from a specific version home.
- * Soft-deletes to ~/.agents/.trash/subagents/.
- */
 export function removeSubagentFromVersion(agent, version, subagentName) {
     const versionHome = getVersionHomePath(agent, version);
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
     const trashDir = path.join(getTrashSubagentsDir(), agent, version, subagentName);
-    // Registry-driven soft-delete: files land as `<basename>.<stamp>`, dirs as
-    // `<stamp>/`, matching the prior per-agent behavior for every layout.
     return trashSubagentFromHome(agent, versionHome, subagentName, trashDir, stamp);
 }

package/dist/lib/summarizer/config.d.ts

@@ -1,46 +1,9 @@
-/**
- * Session-summarizer configuration (PHNX-3939).
- *
- * Resolves the three knobs behind the daemon summarizer — enabled / base URL /
- * model — from `agents config` (`summarizer.*`, user-scope in the central
- * agents.yaml) with a per-process env override
- * (`AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` /
- * `AGENTS_SUMMARIZER_MODEL`). Off by default: with no config and no env, the
- * summarizer is disabled and makes zero model calls.
- *
- * `isSummarizerReady()` is memoized on a short TTL because the display merge
- * (the watch-stream projections) calls it once per session row — a fresh
- * agents.yaml read per row would defeat the "blazing fast" requirement.
- */
 export interface SummarizerConfig {
     enabled: boolean;
-    /** Anthropic-wire base URL (Ollama/vLLM/LiteLLM), or undefined when unconfigured. */
     baseUrl?: string;
-    /** Model id to request, or undefined when unconfigured. */
     model?: string;
 }
-/**
- * Resolve the full summarizer config. Env overrides the stored config key by key;
- * an unset env var falls through to `agents config`, then to the built-in
- * default (disabled). Never throws — a missing/corrupt config reads as unset.
- */
 export declare function resolveSummarizerConfig(env?: NodeJS.ProcessEnv): SummarizerConfig;
-/**
- * True only when the summarizer is enabled AND has a base URL + model to call.
- * A configuration that is `enabled` but missing an endpoint cannot produce a
- * summary, so it is treated as unconfigured (the service no-ops, the merge marks
- * `skipped`) rather than erroring on every tick.
- */
 export declare function isSummarizerRunnable(config: SummarizerConfig): boolean;
-/**
- * Memoized "will a summary actually be produced?" check for the hot merge path.
- * Reflects {@link isSummarizerRunnable} — enabled AND a base URL AND a model —
- * NOT just `enabled`, because an enabled-but-unconfigured summarizer computes
- * nothing, so a row with no cached summary must read `skipped`, not a `pending`
- * that never resolves (the exact case: `summarizer.enabled on` set before the
- * endpoint). TTL keeps a config change visible within a few seconds without a
- * per-row agents.yaml read.
- */
 export declare function isSummarizerReady(nowMs?: number): boolean;
-/** Test seam: drop the memoized ready flag so the next read re-resolves. */
 export declare function resetSummarizerReadyCacheForTest(): void;

package/dist/lib/summarizer/config.js

@@ -1,19 +1,4 @@
-/**
- * Session-summarizer configuration (PHNX-3939).
- *
- * Resolves the three knobs behind the daemon summarizer — enabled / base URL /
- * model — from `agents config` (`summarizer.*`, user-scope in the central
- * agents.yaml) with a per-process env override
- * (`AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` /
- * `AGENTS_SUMMARIZER_MODEL`). Off by default: with no config and no env, the
- * summarizer is disabled and makes zero model calls.
- *
- * `isSummarizerReady()` is memoized on a short TTL because the display merge
- * (the watch-stream projections) calls it once per session row — a fresh
- * agents.yaml read per row would defeat the "blazing fast" requirement.
- */
 import { getConfigValue } from '../device-config.js';
-/** Parse a boolean-ish env value; undefined when the var is unset. */
 function envBool(raw) {
     if (raw === undefined)
         return undefined;
@@ -28,11 +13,6 @@ function envString(raw) {
     const v = raw?.trim();
     return v ? v : undefined;
 }
-/**
- * Resolve the full summarizer config. Env overrides the stored config key by key;
- * an unset env var falls through to `agents config`, then to the built-in
- * default (disabled). Never throws — a missing/corrupt config reads as unset.
- */
 export function resolveSummarizerConfig(env = process.env) {
     let storedEnabled;
     let storedBaseUrl;
@@ -43,33 +23,17 @@ export function resolveSummarizerConfig(env = process.env) {
         storedModel = getConfigValue('summarizer.model').value;
     }
     catch {
-        // A missing/corrupt config store must not break the read path — treat as unset.
     }
     const enabled = envBool(env.AGENTS_SUMMARIZER_ENABLED) ?? storedEnabled ?? false;
     const baseUrl = envString(env.AGENTS_SUMMARIZER_BASEURL) ?? envString(storedBaseUrl);
     const model = envString(env.AGENTS_SUMMARIZER_MODEL) ?? envString(storedModel);
     return { enabled, baseUrl, model };
 }
-/**
- * True only when the summarizer is enabled AND has a base URL + model to call.
- * A configuration that is `enabled` but missing an endpoint cannot produce a
- * summary, so it is treated as unconfigured (the service no-ops, the merge marks
- * `skipped`) rather than erroring on every tick.
- */
 export function isSummarizerRunnable(config) {
     return config.enabled && Boolean(config.baseUrl) && Boolean(config.model);
 }
 let cachedReady = null;
 const READY_TTL_MS = 3_000;
-/**
- * Memoized "will a summary actually be produced?" check for the hot merge path.
- * Reflects {@link isSummarizerRunnable} — enabled AND a base URL AND a model —
- * NOT just `enabled`, because an enabled-but-unconfigured summarizer computes
- * nothing, so a row with no cached summary must read `skipped`, not a `pending`
- * that never resolves (the exact case: `summarizer.enabled on` set before the
- * endpoint). TTL keeps a config change visible within a few seconds without a
- * per-row agents.yaml read.
- */
 export function isSummarizerReady(nowMs = Date.now()) {
     if (cachedReady && nowMs - cachedReady.at < READY_TTL_MS)
         return cachedReady.value;
@@ -77,7 +41,6 @@ export function isSummarizerReady(nowMs = Date.now()) {
     cachedReady = { at: nowMs, value };
     return value;
 }
-/** Test seam: drop the memoized ready flag so the next read re-resolves. */
 export function resetSummarizerReadyCacheForTest() {
     cachedReady = null;
 }

package/dist/lib/summarizer/pass.d.ts

@@ -1,33 +1,17 @@
-/**
- * One session-summarizer pass (PHNX-3939) — the work the background
- * SessionSummarizerService does per tick, factored out so it is testable with an
- * injected model stub and no daemon scaffolding.
- *
- * Off the request path by construction: it reads THIS box's already-published
- * live sessions (the warm cache the session-state service writes — never a fresh
- * gather) and, per session, reuses the transcript-keyed `session_summaries` row
- * until the transcript bytes change, so an unchanged session costs one indexed
- * read and zero model calls. When the summarizer is disabled or has no endpoint,
- * the pass does nothing at all.
- */
 import type { ActiveSession } from '../session/active.js';
 import { type SummarizerConfig } from './config.js';
 import { summarize as defaultSummarize } from './summarize.js';
 interface SummarizerPassOptions {
     now?: number;
     config?: SummarizerConfig;
-    /** Live sessions to consider; default = this box's warm local-session cache. */
     sessions?: ActiveSession[];
-    /** Injectable model call (tests stub the endpoint here). */
     summarizeImpl?: typeof defaultSummarize;
     signal?: AbortSignal;
     maxPerTick?: number;
-    /** Injectable stat for tests; defaults to fs.statSync. */
     statFile?: (p: string) => {
         mtimeMs: number;
         size: number;
     };
-    /** Skip the reader-recency gate (tests pass sessions directly). */
     requireReader?: boolean;
 }
 interface SummarizerPassResult {
@@ -36,9 +20,5 @@ interface SummarizerPassResult {
     reused: number;
     skipped: number;
 }
-/**
- * Run one pass. Returns per-outcome counts. Never throws — a per-session failure
- * is isolated so one bad transcript can't stall the whole tick.
- */
 export declare function runSummarizerPass(opts?: SummarizerPassOptions): Promise<SummarizerPassResult>;
 export {};

package/dist/lib/summarizer/pass.js

@@ -1,37 +1,14 @@
-/**
- * One session-summarizer pass (PHNX-3939) — the work the background
- * SessionSummarizerService does per tick, factored out so it is testable with an
- * injected model stub and no daemon scaffolding.
- *
- * Off the request path by construction: it reads THIS box's already-published
- * live sessions (the warm cache the session-state service writes — never a fresh
- * gather) and, per session, reuses the transcript-keyed `session_summaries` row
- * until the transcript bytes change, so an unchanged session costs one indexed
- * read and zero model calls. When the summarizer is disabled or has no endpoint,
- * the pass does nothing at all.
- */
 import * as fs from 'node:fs';
 import { readSessionSummary, readSessionSummaryAny, writeSessionSummary, } from '../session/db.js';
 import { isActiveSessionsJournalReaderRecent, readActiveSessionsCache, } from '../session/session-cache.js';
 import { resolveSummarizerConfig, isSummarizerRunnable } from './config.js';
 import { summarize as defaultSummarize } from './summarize.js';
-/** Max sessions summarized per tick — a debounce ceiling on local-model calls. */
 const SUMMARIZER_MAX_PER_TICK = 8;
-/** Narration headlines handed to the model per session — the recent tail, not the history. */
 const SUMMARIZER_STEP_INPUT = 12;
-/**
- * Merge model checkpoint TEXTS with any prior stored checkpoints so a line that
- * already existed keeps its original `at`, and only genuinely new lines get
- * stamped `now`. Order follows the model output (newest last).
- */
 function stampCheckpoints(texts, prior, nowIso) {
     const priorAt = new Map((prior ?? []).map((c) => [c.text, c.at]));
     return texts.map((text) => ({ text, at: priorAt.get(text) ?? nowIso }));
 }
-/**
- * Run one pass. Returns per-outcome counts. Never throws — a per-session failure
- * is isolated so one bad transcript can't stall the whole tick.
- */
 export async function runSummarizerPass(opts = {}) {
     const now = opts.now ?? Date.now();
     const config = opts.config ?? resolveSummarizerConfig();
@@ -42,7 +19,6 @@ export async function runSummarizerPass(opts = {}) {
     }
     let sessions = opts.sessions;
     if (!sessions) {
-        // Reader-gated like the active-sessions warm tick: no watcher, no work.
         if (opts.requireReader !== false && !isActiveSessionsJournalReaderRecent(now))
             return result;
         sessions = readActiveSessionsCache('local')?.sessions ?? [];
@@ -70,9 +46,8 @@ export async function runSummarizerPass(opts = {}) {
             stamp = { fileMtimeMs: Math.round(st.mtimeMs), fileSize: st.size };
         }
         catch {
-            continue; // transcript unreadable this tick — try again next time
+            continue;
         }
-        // Cached for these exact bytes → never recompute (the core "blazing fast" rule).
         if (readSessionSummary(id, stamp)) {
             result.reused++;
             continue;
@@ -81,8 +56,6 @@ export async function runSummarizerPass(opts = {}) {
         const prompt = (s.firstUserMessage ?? s.topic ?? '').trim();
         const prior = readSessionSummaryAny(id);
         if (!prompt) {
-            // No extractable intent yet — cache a skip against these bytes so we don't
-            // re-attempt every tick; a later transcript write (new bytes) retries.
             writeSessionSummary({ id, ...stamp, summary: { summaryState: 'skipped' } });
             result.skipped++;
             continue;
@@ -93,10 +66,6 @@ export async function runSummarizerPass(opts = {}) {
                 todos: s.todos,
                 plan: s.plan,
                 phase: s.phase,
-                // The agent's own narration headlines, when the timeline pass has
-                // folded them (PHNX-3939) — the model's progress input was previously
-                // only the checklist, which many sessions never write. Optional by
-                // construction: a row with no timeline passes nothing extra.
                 ...(s.timeline?.steps.length
                     ? { steps: s.timeline.steps.slice(-SUMMARIZER_STEP_INPUT).map((step) => step.text) }
                     : {}),
@@ -111,8 +80,6 @@ export async function runSummarizerPass(opts = {}) {
             continue;
         }
         const entry = {
-            // Goal is computed ONCE at first sight — a prior goal is kept across
-            // progress deltas so it stays stable while checkpoints/checklist refresh.
             goal: prior?.goal ?? computed.goal,
             checkpoints: stampCheckpoints(computed.checkpoints, prior?.checkpoints, nowIso),
             summaryChecklist: computed.checklist,