@pruddiman/hem 0.0.1-beta-5671db0

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

@@ -0,0 +1,140 @@
+/**
+ * LLM-assisted cross-reference agent for Hem.
+ *
+ * Post-processing agent that runs AFTER the organization agent.
+ * Reads all generated documentation files and adds inter-document links
+ * (cross-references) to improve navigation.
+ *
+ * Architecture (v2 — parallel workers with broadcast):
+ *   - Reads all generated docs from disk.
+ *   - Adds cross-reference links between related pages.
+ *   - For large file sets (>8 files), splits work across N parallel workers.
+ *   - Workers communicate via an MCP broadcast tool + prompt injection.
+ *   - The orchestrator intercepts broadcast tool calls via SSE and relays
+ *     messages to all peer workers + their active subagents.
+ *   - For small file sets (≤8 files), falls back to the single-agent path.
+ *   - The pipeline discovers the final file set by scanning disk afterward.
+ */
+import type { Provider } from "../providers/types.js";
+import { BaseAgent } from "./base-agent.js";
+/** File count threshold: use parallel workers above this, single agent below. */
+export declare const XREF_PARALLEL_THRESHOLD = 8;
+/**
+ * Hard ceiling on parallel cross-ref workers.  The actual worker count is
+ * `min(XREF_MAX_WORKERS, computeMaxConcurrency(), fileCount)`.
+ * The arbiter is excluded from this cap (it is lightweight).
+ */
+export declare const XREF_MAX_WORKERS = 4;
+/** Parameters for the cross-reference agent prompt. */
+export interface CrossRefPromptParams {
+    /** Project name. */
+    projectName: string;
+    /** Absolute path to the destination directory. */
+    destinationPath: string;
+    /** Relative paths of all generated documentation files. */
+    allDocFiles: string[];
+}
+/** Parameters for a parallel cross-ref worker prompt. */
+export interface CrossRefWorkerPromptParams {
+    /** Project name. */
+    projectName: string;
+    /** Absolute path to the destination directory. */
+    destinationPath: string;
+    /** Files assigned to THIS worker (relative paths). */
+    assignedFiles: string[];
+    /** ALL documentation files across all workers (for cross-reference awareness). */
+    allDocFiles: string[];
+    /** Label for this worker, e.g. "xref-worker-1". */
+    workerLabel: string;
+    /** Total number of parallel workers. */
+    totalWorkers: number;
+}
+/** A single cross-ref worker assignment: label → file list. */
+export interface XrefWorkerAssignment {
+    label: string;
+    files: string[];
+}
+/**
+ * An agent that reads all generated documentation and adds inter-document
+ * cross-reference links for improved navigation.
+ *
+ * Edits files directly via the edit tool. The pipeline discovers the
+ * final file set by scanning disk afterward.
+ */
+export declare class CrossRefAgent extends BaseAgent {
+    constructor(provider: Provider);
+    /**
+     * Run the cross-reference pass over all generated documentation.
+     * Automatically selects single-agent or parallel mode based on file count.
+     *
+     * @param params  - Cross-reference parameters including file paths.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    run(params: CrossRefPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Single-agent cross-reference pass (original behavior).
+     * Used when file count is ≤ XREF_PARALLEL_THRESHOLD.
+     */
+    runSingle(params: CrossRefPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Parallel cross-reference pass using multiple workers with an arbiter.
+     *
+     * 1. Computes worker count from resource limits (arbiter excluded).
+     * 2. Assigns files to workers via round-robin.
+     * 3. Subscribes to SSE events for broadcast interception.
+     * 4. Creates an arbiter session (long-lived coordinator).
+     * 5. Creates N worker sessions in parallel.
+     * 6. Relays broadcasts with targeted routing:
+     *    - Worker → arbiter only.
+     *    - Arbiter → @tagged worker(s) only (or all if @all-workers / no tag).
+     *    - Completed sessions are excluded from relay.
+     * 7. Kills worker sessions immediately on completion (abort + delete).
+     * 8. Intercepts RECALL: broadcasts to respawn a worker for fixes.
+     * 9. Sends a final prompt to the arbiter so it can wrap up.
+     * 10. Kills the arbiter session.
+     */
+    runParallel(params: CrossRefPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Kill a session: abort any running work, then delete the session.
+     * Best-effort — failures are logged but not thrown.
+     */
+    private killSession;
+    /**
+     * Spawn a recalled worker session to apply specific fixes.
+     *
+     * Called when the arbiter broadcasts `RECALL: @xref-worker-N <instructions>`.
+     * Creates a new session with the worker's original file assignment and a
+     * focused prompt containing the fix instructions.  The session is killed
+     * immediately after completion.
+     */
+    private runRecalledWorker;
+    /**
+     * Builds the single-agent cross-reference prompt (original behavior).
+     */
+    static buildPrompt(params: CrossRefPromptParams): string;
+    /**
+     * Builds the prompt for a parallel cross-ref worker.
+     *
+     * Each worker gets:
+     *   - A scoped identity (e.g. "xref-worker-1 of 3")
+     *   - Its assigned file subset
+     *   - The full file list for cross-reference awareness
+     *   - Instructions for using the broadcast tool
+     *   - Scoped task list (only edit YOUR files)
+     */
+    static buildWorkerPrompt(params: CrossRefWorkerPromptParams): string;
+}
+/**
+ * Assigns documentation files to cross-ref workers using round-robin distribution.
+ *
+ * Files are sorted alphabetically first so that files in the same
+ * directory tend to land on adjacent workers, preserving some locality.
+ * Then they are dealt out in order: file 0 → worker 1, file 1 → worker 2,
+ * …, wrapping around. This guarantees perfectly balanced workloads (±1 file).
+ *
+ * @param files      - Relative file paths (e.g. "auth/overview.md").
+ * @param maxWorkers - Maximum number of workers to create.
+ * @returns An array of worker assignments, each with a label and file list.
+ */
+export declare function assignXrefFilesToWorkers(files: string[], maxWorkers: number): XrefWorkerAssignment[];