@pruddiman/hem 0.0.1-beta-5671db0

package/dist/agents/architecture-agent.js

@@ -0,0 +1,459 @@
+/**
+ * LLM-assisted architecture overview generation agent for Hem.
+ *
+ * Post-processing agent that runs AFTER cross-ref and organization agents.
+ * Uses an OpenCode session to generate the top-level `architecture.md`
+ * document by reading all generated documentation files and exploration
+ * findings.
+ *
+ * Architecture (v2):
+ *   - The agent writes `architecture.md` directly via the edit tool.
+ *   - The pipeline discovers what was written by scanning disk afterward.
+ *   - Reads existing generated docs from disk for context.
+ *   - Runs as the last content agent in the pipeline (after org + xref).
+ */
+import pLimit from "p-limit";
+import { extractJSON } from "../helpers/parsing.js";
+import { BaseAgent } from "./base-agent.js";
+import { computeMaxConcurrency } from "../resources.js";
+import { AuthExpiredError } from "../auth.js";
+// ── Constants ───────────────────────────────────────────────────────────
+/**
+ * Maximum character count for the full architecture prompt before
+ * switching to chunked mode. Set conservatively below typical LLM
+ * context windows (~200K tokens ≈ ~800K chars) to leave room for
+ * the agent's tool interactions and responses.
+ */
+export const ARCH_PROMPT_CHAR_LIMIT = 400_000;
+/**
+ * Target character count per chunk when splitting findings and group
+ * summaries for chunked architecture generation. Each chunk should
+ * comfortably fit in a single prompt alongside instructions.
+ */
+export const ARCH_CHUNK_TARGET_CHARS = 150_000;
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that uses an LLM to generate the architecture overview
+ * document for a project's documentation.
+ *
+ * Writes `architecture.md` directly via the edit tool. The pipeline
+ * discovers what was written by scanning disk afterward.
+ */
+export class ArchitectureAgent extends BaseAgent {
+    constructor(provider) {
+        super(provider);
+    }
+    /**
+     * Run the architecture overview generation pipeline.
+     *
+     * When the full prompt would exceed `ARCH_PROMPT_CHAR_LIMIT`, the agent
+     * automatically switches to chunked mode: findings and group summaries
+     * are split into manageable batches, each batch is summarised by a
+     * dedicated session, and a final synthesis session combines the chunk
+     * summaries into the architecture overview.
+     *
+     * @param params  - All inputs needed for the architecture prompt.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    async run(params, verbose) {
+        const tag = "arch-agent";
+        // 1. Build prompt and check size
+        const prompt = ArchitectureAgent.buildPrompt(params);
+        if (verbose) {
+            verbose(`[${tag}] Prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. If prompt exceeds limit, use chunked mode
+        if (prompt.length > ARCH_PROMPT_CHAR_LIMIT) {
+            if (verbose) {
+                verbose(`[${tag}] Prompt exceeds ${ARCH_PROMPT_CHAR_LIMIT.toLocaleString()} char limit, switching to chunked mode`);
+            }
+            return this.runChunked(params, verbose);
+        }
+        // 3. Create a new session (normal mode)
+        const sessionId = await this.createSession("Hem: architecture overview");
+        if (verbose) {
+            verbose(`[${tag}] Session created: ${sessionId}`);
+        }
+        // 4. Send prompt and wait for response — use hem-arch agent
+        await this.provider.prompt(sessionId, prompt, { agent: "hem-arch" });
+        if (verbose) {
+            verbose(`[${tag}] Agent completed`);
+        }
+    }
+    /**
+     * Chunked architecture generation for large projects.
+     *
+     * 1. Splits exploration findings and group summaries into chunks that
+     *    fit within context limits.
+     * 2. Runs a sequential summarisation session for each chunk.
+     * 3. Runs a final synthesis session that combines all chunk summaries
+     *    and writes `architecture.md` via the edit tool.
+     */
+    async runChunked(params, verbose) {
+        const tag = "arch-agent";
+        // 1. Chunk findings + group summaries
+        const chunks = ArchitectureAgent.chunkFindings(params.allFindings, params.allGroupSummaries, ARCH_CHUNK_TARGET_CHARS);
+        if (verbose) {
+            verbose(`[${tag}] Split into ${chunks.length} chunks for summarisation`);
+        }
+        // 2. Summarise chunks in parallel (bounded by resource concurrency)
+        const concurrency = computeMaxConcurrency();
+        const limit = pLimit(concurrency);
+        const settled = await Promise.allSettled(chunks.map((chunk, i) => limit(async () => {
+            const chunkLabel = `chunk-${i + 1}/${chunks.length}`;
+            if (verbose) {
+                verbose(`[${tag}] Summarising ${chunkLabel} (${chunk.findings.length} findings, ${chunk.groups.length} groups)`);
+            }
+            const chunkPrompt = ArchitectureAgent.buildChunkSummaryPrompt(params.projectName, chunk.findings, chunk.groups, i, chunks.length);
+            if (verbose) {
+                verbose(`[${tag}] ${chunkLabel} prompt: ${chunkPrompt.length.toLocaleString()} chars`);
+            }
+            const sessionId = await this.createSession(`Hem: arch ${chunkLabel}`);
+            const response = await this.provider.prompt(sessionId, chunkPrompt, { agent: "hem-arch" }) ?? "";
+            const summary = ArchitectureAgent.parseChunkSummary(response, i);
+            if (verbose) {
+                verbose(`[${tag}] ${chunkLabel} summarised: ${summary.patterns.length} patterns, ${summary.components.length} components`);
+            }
+            return summary;
+        })));
+        // Collect results; use empty fallback for failed chunks so synthesis still runs.
+        // Re-throw AuthExpiredError immediately.
+        const chunkSummaries = [];
+        for (let i = 0; i < settled.length; i++) {
+            const result = settled[i];
+            if (result.status === "fulfilled") {
+                chunkSummaries.push(result.value);
+            }
+            else {
+                if (result.reason instanceof AuthExpiredError) {
+                    throw result.reason;
+                }
+                if (verbose) {
+                    const msg = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                    verbose(`[${tag}] chunk-${i + 1}/${chunks.length} failed: ${msg}`);
+                }
+                // Push an empty fallback so the synthesis index is not skewed
+                chunkSummaries.push(ArchitectureAgent.parseChunkSummary("", i));
+            }
+        }
+        // 3. Final synthesis — combine chunk summaries into architecture.md
+        if (verbose) {
+            verbose(`[${tag}] Running synthesis from ${chunkSummaries.length} chunk summaries`);
+        }
+        const synthesisPrompt = ArchitectureAgent.buildSynthesisPrompt(params, chunkSummaries);
+        if (verbose) {
+            verbose(`[${tag}] Synthesis prompt: ${synthesisPrompt.length.toLocaleString()} chars`);
+        }
+        const synthSessionId = await this.createSession("Hem: architecture synthesis");
+        if (verbose) {
+            verbose(`[${tag}] Synthesis session created: ${synthSessionId}`);
+        }
+        await this.provider.prompt(synthSessionId, synthesisPrompt, { agent: "hem-arch" });
+        if (verbose) {
+            verbose(`[${tag}] Chunked architecture generation completed`);
+        }
+    }
+    // ── Static helpers (pure functions, easy to unit test) ───────────────
+    /**
+     * Builds the architecture overview prompt from exploration findings
+     * and group summaries.
+     */
+    static buildPrompt(params) {
+        const { projectName, sourceRoot, destinationPath, allFindings, allGroupSummaries, allDocFiles, } = params;
+        const parts = [];
+        // 1. System-level instructions
+        parts.push(`Generate a comprehensive architecture overview that gives readers a mental model`, `of the entire system before they dive into individual feature or module pages.`, "", `**Write files directly using the edit tool.** Do NOT return Markdown content`, `in the response text. Instead, use the edit tool to create \`architecture.md\``, `in the destination directory. When done, stop.`, "");
+        // 2. Where to write
+        parts.push("## Destination", "", `Write the architecture overview to: \`${destinationPath}/architecture.md\``, "");
+        // 3. Quality standards
+        parts.push("## Quality Standard: Synthesize Questions Across the System", "", `Your primary quality standard is: **the architecture overview must synthesize`, `operational questions from ALL exploration groups into a system-wide view,`, `identify cross-cutting patterns, and link to feature pages for detailed answers.**`, "", `### Synthesize operational questions across groups`, "", `- Review the questions and integrations from EVERY group's exploration findings.`, `- Identify system-wide patterns (shared monitoring, common databases, etc.).`, `- Surface these patterns in dedicated architecture sections.`, `- Link to specific feature pages where full answers live — do NOT duplicate.`, "", `### Address cross-cutting concerns`, "", `- Secrets rotation, monitoring, shared databases, error handling, auth, etc.`, "");
+        parts.push("## Documentation quality standards", "");
+        parts.push(`1. **WHAT and WHY first**: Start with what the application is and why it exists.`, "", `2. **System-level Mermaid diagrams**: Always generate a system topology diagram.`, `   Add more diagrams based on complexity signals.`, "", `3. **No verbatim source code**: Reference files by path only.`, "", `4. **Google Markdown style guide**: ATX headings, single H1, informative links.`, "", `5. **Link to detail pages, don't duplicate**: Reference feature pages.`, "");
+        // 4. Task description
+        parts.push("## Your task", "");
+        parts.push(`Generate the architecture overview for **${projectName}**.`, "", `**Source root**: ${sourceRoot}`, "");
+        // 5. Read existing generated docs for context
+        if (allDocFiles.length > 0) {
+            parts.push("## Generated documentation files", "");
+            parts.push("These documentation files have already been generated. Read them using tools", "to understand what content exists, then link to them from the architecture overview.", "");
+            for (const docFile of allDocFiles) {
+                parts.push(`- \`${destinationPath}/${docFile}\``);
+            }
+            parts.push("");
+        }
+        // 6. Exploration findings
+        parts.push("## Exploration findings", "");
+        if (allFindings.length > 0) {
+            parts.push("The exploration phase discovered these findings across all file groups:", "");
+            parts.push(ArchitectureAgent.formatAllFindings(allFindings));
+        }
+        else {
+            parts.push("No exploration findings available. Use tools to read source files directly.", "");
+        }
+        // 7. File groups
+        parts.push("## File groups in this project", "");
+        parts.push(ArchitectureAgent.formatGroupSummaries(allGroupSummaries));
+        parts.push("");
+        // 8. How to work
+        parts.push("## How to work", "");
+        parts.push(`1. **Read generated docs**: Use tools to read the generated documentation files`, `   for context about what has already been documented.`, `2. **Read key source files**: Use tools to read entry points and config files.`, `3. **Synthesize questions across groups**: Identify system-wide patterns.`, `4. **Generate diagrams**: Always generate a system topology Mermaid diagram.`, `5. **Write the file**: Use the edit tool to write \`architecture.md\`.`, `6. **Link to detail pages**: Use relative paths to link to generated doc pages.`, "");
+        // 9. Document structure
+        parts.push("## Document structure", "");
+        parts.push(`Follow this general structure for \`architecture.md\`:`, "", `- \`# ${projectName} — Architecture Overview\``, `- What is ${projectName}?`, `- Why does it exist?`, `- System Architecture (with Mermaid diagram)`, `- Data Flow (with diagram if applicable)`, `- Infrastructure`, `- Key Design Decisions`, `- Cross-Cutting Concerns`, `- Component Index (links to generated pages)`, "");
+        // 10. Done
+        parts.push("## When you are done", "");
+        parts.push(`After writing \`architecture.md\` using the edit tool, simply stop.`, `Do NOT return a JSON manifest or any other structured output.`, `The pipeline will scan the destination directory to discover what you wrote.`);
+        return parts.join("\n");
+    }
+    /**
+     * Formats all exploration findings for the architecture prompt.
+     */
+    static formatAllFindings(allFindings) {
+        return allFindings
+            .map((f) => `### Group: ${f.groupId}\n\n${f.text}`)
+            .join("\n\n");
+    }
+    /**
+     * Formats file group summaries as a list for the prompt.
+     */
+    static formatGroupSummaries(groups) {
+        if (groups.length === 0)
+            return "No file groups defined.";
+        const parts = [];
+        for (const group of groups) {
+            parts.push(`- **${group.label}** (${group.id})`);
+            parts.push(`  Files: ${group.files.join(", ")}`);
+        }
+        return parts.join("\n");
+    }
+    // ── Chunked-mode helpers ──────────────────────────────────────────────
+    /**
+     * Split exploration findings and group summaries into chunks that each
+     * stay under `targetChars` when formatted.
+     *
+     * Findings and their corresponding group summaries are kept together.
+     * Groups without findings are distributed across chunks to balance
+     * size.
+     *
+     * @returns Array of chunks, each with a subset of findings and groups.
+     */
+    static chunkFindings(allFindings, allGroupSummaries, targetChars) {
+        // Build a lookup of group summaries by id for quick access
+        const groupById = new Map(allGroupSummaries.map((g) => [g.id, g]));
+        // Pair each finding with its group summary and compute formatted size
+        const items = allFindings.map((f) => {
+            const group = groupById.get(f.groupId);
+            const groupText = group
+                ? ArchitectureAgent.formatGroupSummaries([group])
+                : "";
+            return {
+                finding: f,
+                group,
+                charSize: f.text.length + groupText.length,
+            };
+        });
+        // Collect group summaries that have no corresponding findings
+        const findingGroupIds = new Set(allFindings.map((f) => f.groupId));
+        const orphanGroups = allGroupSummaries.filter((g) => !findingGroupIds.has(g.id));
+        // Greedily pack items into chunks
+        const chunks = [];
+        let currentChunk = { findings: [], groups: [] };
+        let currentSize = 0;
+        for (const item of items) {
+            // Start a new chunk if adding this item would exceed the target
+            // (unless the current chunk is empty — always add at least one item)
+            if (currentSize > 0 && currentSize + item.charSize > targetChars) {
+                chunks.push(currentChunk);
+                currentChunk = { findings: [], groups: [] };
+                currentSize = 0;
+            }
+            currentChunk.findings.push(item.finding);
+            if (item.group) {
+                currentChunk.groups.push(item.group);
+            }
+            currentSize += item.charSize;
+        }
+        // Push last chunk if non-empty
+        if (currentChunk.findings.length > 0 || orphanGroups.length > 0) {
+            chunks.push(currentChunk);
+        }
+        // Distribute orphan groups across chunks (round-robin)
+        if (orphanGroups.length > 0 && chunks.length > 0) {
+            for (let i = 0; i < orphanGroups.length; i++) {
+                chunks[i % chunks.length].groups.push(orphanGroups[i]);
+            }
+        }
+        // Edge case: no findings and no groups — return a single empty chunk
+        if (chunks.length === 0) {
+            chunks.push({ findings: [], groups: [] });
+        }
+        return chunks;
+    }
+    /**
+     * Build a prompt for summarising a single chunk of findings and groups.
+     *
+     * The LLM should return a structured JSON summary that can be fed
+     * into the synthesis phase.
+     */
+    static buildChunkSummaryPrompt(projectName, findings, groups, chunkIndex, totalChunks) {
+        const parts = [];
+        parts.push(`Summarise chunk ${chunkIndex + 1} of ${totalChunks} for the **${projectName}**`, `project as part of an architecture analysis.`, "", `Read the exploration findings and group summaries below, then produce a`, `structured JSON summary of the architectural insights.`, "", `Respond with ONLY a JSON object inside a \`\`\`json code fence. No other text.`, "", `The JSON must match this schema:`, "```json", JSON.stringify({
+            patterns: ["Architectural pattern descriptions"],
+            crossCuttingConcerns: ["Cross-cutting concern descriptions"],
+            integrations: ["External integration descriptions"],
+            components: ["Component name: responsibility"],
+            dataFlows: ["Data flow or interaction pattern descriptions"],
+            rawSummary: "2-3 paragraph summary of this chunk's architecture",
+        }, null, 2), "```", "");
+        // Findings
+        parts.push("## Exploration findings for this chunk", "");
+        if (findings.length > 0) {
+            parts.push(ArchitectureAgent.formatAllFindings(findings));
+        }
+        else {
+            parts.push("No exploration findings in this chunk.", "");
+        }
+        // Groups
+        parts.push("## File groups in this chunk", "");
+        if (groups.length > 0) {
+            parts.push(ArchitectureAgent.formatGroupSummaries(groups));
+        }
+        else {
+            parts.push("No file groups in this chunk.");
+        }
+        parts.push("");
+        return parts.join("\n");
+    }
+    /**
+     * Parse the LLM response from a chunk summarisation session into an
+     * `ArchChunkSummary`.
+     *
+     * Falls back to a minimal summary containing just the raw response
+     * text if JSON extraction fails — chunked mode should be resilient.
+     */
+    static parseChunkSummary(response, chunkIndex) {
+        const fallback = {
+            chunkIndex,
+            patterns: [],
+            crossCuttingConcerns: [],
+            integrations: [],
+            components: [],
+            dataFlows: [],
+            rawSummary: response.slice(0, 5000),
+        };
+        try {
+            const json = extractJSON(response);
+            const parsed = JSON.parse(json);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return fallback;
+            }
+            const obj = parsed;
+            const toStringArray = (val) => {
+                if (!Array.isArray(val))
+                    return [];
+                return val.filter((v) => typeof v === "string");
+            };
+            return {
+                chunkIndex,
+                patterns: toStringArray(obj.patterns),
+                crossCuttingConcerns: toStringArray(obj.crossCuttingConcerns),
+                integrations: toStringArray(obj.integrations),
+                components: toStringArray(obj.components),
+                dataFlows: toStringArray(obj.dataFlows),
+                rawSummary: typeof obj.rawSummary === "string"
+                    ? obj.rawSummary
+                    : response.slice(0, 5000),
+            };
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /**
+     * Build the final synthesis prompt that combines all chunk summaries
+     * and instructs the agent to write `architecture.md`.
+     *
+     * Reuses the same quality standards and document structure as the
+     * normal-mode `buildPrompt()`, but substitutes chunk summaries for
+     * the raw findings.
+     */
+    static buildSynthesisPrompt(params, chunkSummaries) {
+        const { projectName, sourceRoot, destinationPath, allDocFiles } = params;
+        const parts = [];
+        // 1. System-level instructions
+        parts.push(`Generate a comprehensive architecture overview that gives readers a mental model`, `of the entire system before they dive into individual feature or module pages.`, "", `**Write files directly using the edit tool.** Do NOT return Markdown content`, `in the response text. Instead, use the edit tool to create \`architecture.md\``, `in the destination directory. When done, stop.`, "", `**NOTE**: This project is too large for a single-pass analysis. The findings`, `below are pre-summarised from ${chunkSummaries.length} analysis chunks.`, `Synthesize them into a unified architecture overview.`, "");
+        // 2. Where to write
+        parts.push("## Destination", "", `Write the architecture overview to: \`${destinationPath}/architecture.md\``, "");
+        // 3. Quality standards (same as buildPrompt)
+        parts.push("## Quality Standard: Synthesize Questions Across the System", "", `Your primary quality standard is: **the architecture overview must synthesize`, `operational questions from ALL exploration groups into a system-wide view,`, `identify cross-cutting patterns, and link to feature pages for detailed answers.**`, "");
+        parts.push("## Documentation quality standards", "");
+        parts.push(`1. **WHAT and WHY first**: Start with what the application is and why it exists.`, "", `2. **System-level Mermaid diagrams**: Always generate a system topology diagram.`, `   Add more diagrams based on complexity signals.`, "", `3. **No verbatim source code**: Reference files by path only.`, "", `4. **Google Markdown style guide**: ATX headings, single H1, informative links.`, "", `5. **Link to detail pages, don't duplicate**: Reference feature pages.`, "");
+        // 4. Task description
+        parts.push("## Your task", "");
+        parts.push(`Generate the architecture overview for **${projectName}**.`, "", `**Source root**: ${sourceRoot}`, "");
+        // 5. Read existing generated docs for context
+        if (allDocFiles.length > 0) {
+            parts.push("## Generated documentation files", "");
+            parts.push("These documentation files have already been generated. Read them using tools", "to understand what content exists, then link to them from the architecture overview.", "");
+            for (const docFile of allDocFiles) {
+                parts.push(`- \`${destinationPath}/${docFile}\``);
+            }
+            parts.push("");
+        }
+        // 6. Chunk summaries (replacing raw findings)
+        parts.push("## Pre-analysed architecture summaries", "");
+        parts.push(`The following summaries were generated from ${chunkSummaries.length} chunks`, `of exploration findings. Synthesize them into a unified view.`, "");
+        for (const summary of chunkSummaries) {
+            parts.push(`### Chunk ${summary.chunkIndex + 1}`, "");
+            if (summary.patterns.length > 0) {
+                parts.push("**Architectural patterns**:");
+                for (const p of summary.patterns) {
+                    parts.push(`- ${p}`);
+                }
+                parts.push("");
+            }
+            if (summary.crossCuttingConcerns.length > 0) {
+                parts.push("**Cross-cutting concerns**:");
+                for (const c of summary.crossCuttingConcerns) {
+                    parts.push(`- ${c}`);
+                }
+                parts.push("");
+            }
+            if (summary.integrations.length > 0) {
+                parts.push("**Integrations**:");
+                for (const i of summary.integrations) {
+                    parts.push(`- ${i}`);
+                }
+                parts.push("");
+            }
+            if (summary.components.length > 0) {
+                parts.push("**Components**:");
+                for (const c of summary.components) {
+                    parts.push(`- ${c}`);
+                }
+                parts.push("");
+            }
+            if (summary.dataFlows.length > 0) {
+                parts.push("**Data flows**:");
+                for (const d of summary.dataFlows) {
+                    parts.push(`- ${d}`);
+                }
+                parts.push("");
+            }
+            if (summary.rawSummary) {
+                parts.push("**Summary**:", "", summary.rawSummary, "");
+            }
+        }
+        // 7. How to work
+        parts.push("## How to work", "");
+        parts.push(`1. **Read generated docs**: Use tools to read the generated documentation files`, `   for context about what has already been documented.`, `2. **Read key source files**: Use tools to read entry points and config files.`, `3. **Synthesize the chunk summaries**: Combine all chunk summaries into a unified view.`, `4. **Generate diagrams**: Always generate a system topology Mermaid diagram.`, `5. **Write the file**: Use the edit tool to write \`architecture.md\`.`, `6. **Link to detail pages**: Use relative paths to link to generated doc pages.`, "");
+        // 8. Document structure
+        parts.push("## Document structure", "");
+        parts.push(`Follow this general structure for \`architecture.md\`:`, "", `- \`# ${projectName} — Architecture Overview\``, `- What is ${projectName}?`, `- Why does it exist?`, `- System Architecture (with Mermaid diagram)`, `- Data Flow (with diagram if applicable)`, `- Infrastructure`, `- Key Design Decisions`, `- Cross-Cutting Concerns`, `- Component Index (links to generated pages)`, "");
+        // 9. Done
+        parts.push("## When you are done", "");
+        parts.push(`After writing \`architecture.md\` using the edit tool, simply stop.`, `Do NOT return a JSON manifest or any other structured output.`, `The pipeline will scan the destination directory to discover what you wrote.`);
+        return parts.join("\n");
+    }
+}

package/dist/agents/base-agent.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Abstract base class for all Hem agents.
+ *
+ * Encapsulates the shared session-creation and auth-error-handling
+ * boilerplate that was previously duplicated across every agent.
+ * Subclasses store their own `run()` signatures and prompt logic —
+ * the base class only provides infrastructure.
+ *
+ * Design decisions:
+ *   - Abstract class (not interface) — the value is shared *implementation*
+ *     (session creation with auth-error handling), not just a type contract.
+ *   - No abstract `run()` — agents have intentionally different parameter
+ *     lists and return types. The base class does not constrain them.
+ *   - Low-level session ops (`promptAsync`, `session.abort`, `event.subscribe`)
+ *     are accessed via `this.provider.session.*` and `this.provider.event.*`.
+ */
+import type { Provider } from "../providers/types.js";
+/**
+ * Abstract base class providing shared session lifecycle management
+ * for all Hem agents.
+ *
+ * Subclasses receive `provider` via the constructor and use
+ * `createSession()` to create new sessions with built-in auth-error
+ * detection and handling.
+ */
+export declare abstract class BaseAgent {
+    protected provider: Provider;
+    constructor(provider: Provider);
+    /**
+     * Create a new session with auth-error handling.
+     *
+     * Encapsulates the session-creation boilerplate:
+     *   1. Calls `this.provider.createSession()`.
+     *   2. Catches thrown errors and checks for auth expiry.
+     *   3. Returns the session ID on success.
+     *
+     * @param _title - Ignored (kept for call-site compatibility; Dispatch
+     *                 pattern has no session titles).
+     * @returns The created session's ID.
+     * @throws {AuthExpiredError} If the creation fails due to expired auth.
+     * @throws {Error} If creation fails for any other reason.
+     */
+    protected createSession(_title?: string): Promise<string>;
+}

package/dist/agents/base-agent.js

@@ -0,0 +1,57 @@
+/**
+ * Abstract base class for all Hem agents.
+ *
+ * Encapsulates the shared session-creation and auth-error-handling
+ * boilerplate that was previously duplicated across every agent.
+ * Subclasses store their own `run()` signatures and prompt logic —
+ * the base class only provides infrastructure.
+ *
+ * Design decisions:
+ *   - Abstract class (not interface) — the value is shared *implementation*
+ *     (session creation with auth-error handling), not just a type contract.
+ *   - No abstract `run()` — agents have intentionally different parameter
+ *     lists and return types. The base class does not constrain them.
+ *   - Low-level session ops (`promptAsync`, `session.abort`, `event.subscribe`)
+ *     are accessed via `this.provider.session.*` and `this.provider.event.*`.
+ */
+import { isAuthExpired, AuthExpiredError } from "../auth.js";
+// ── Base Agent ──────────────────────────────────────────────────────────
+/**
+ * Abstract base class providing shared session lifecycle management
+ * for all Hem agents.
+ *
+ * Subclasses receive `provider` via the constructor and use
+ * `createSession()` to create new sessions with built-in auth-error
+ * detection and handling.
+ */
+export class BaseAgent {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /**
+     * Create a new session with auth-error handling.
+     *
+     * Encapsulates the session-creation boilerplate:
+     *   1. Calls `this.provider.createSession()`.
+     *   2. Catches thrown errors and checks for auth expiry.
+     *   3. Returns the session ID on success.
+     *
+     * @param _title - Ignored (kept for call-site compatibility; Dispatch
+     *                 pattern has no session titles).
+     * @returns The created session's ID.
+     * @throws {AuthExpiredError} If the creation fails due to expired auth.
+     * @throws {Error} If creation fails for any other reason.
+     */
+    async createSession(_title) {
+        try {
+            return await this.provider.createSession();
+        }
+        catch (err) {
+            if (isAuthExpired(err)) {
+                throw new AuthExpiredError("the configured provider", err);
+            }
+            throw err;
+        }
+    }
+}