@yuaone/core 0.1.0

package/dist/debate-orchestrator.d.ts

@@ -0,0 +1,301 @@
+/**
+ * @module debate-orchestrator
+ * @description Multi-Agent Debate system for YUAN.
+ *
+ * Implements a Coder -> Reviewer -> Coder -> Verifier loop:
+ * 1. Coder Agent generates code to solve the task
+ * 2. Reviewer Agent reviews the code, finds issues
+ * 3. Coder Agent addresses the review feedback
+ * 4. Verifier Agent runs tests/builds and makes final judgment
+ *
+ * This significantly reduces hallucination and improves code quality
+ * by having adversarial agents check each other's work.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = DebateOrchestrator.create({
+ *   projectPath: "/home/user/project",
+ *   maxRounds: 3,
+ *   qualityThreshold: 80,
+ *   byokConfig: { provider: "openai", apiKey: "sk-..." },
+ * });
+ *
+ * orchestrator.on("debate:round:start", ({ round }) => {
+ *   console.log(`Round ${round} starting...`);
+ * });
+ *
+ * const result = await orchestrator.debate(
+ *   "Implement a rate limiter middleware",
+ *   "Express.js project with TypeScript",
+ * );
+ *
+ * if (result.success) {
+ *   console.log(`Passed with score ${result.finalScore}`);
+ * }
+ * ```
+ */
+import { EventEmitter } from "node:events";
+import type { BYOKConfig, ToolExecutor } from "./types.js";
+/** Configuration for a debate session */
+export interface DebateConfig {
+    /** Maximum debate rounds (coder->reviewer cycles). Default: 3 */
+    maxRounds: number;
+    /** Minimum quality score to pass (0-100). Default: 80 */
+    qualityThreshold: number;
+    /** LLM model for coder agent */
+    coderModel?: string;
+    /** LLM model for reviewer agent (can be different for diversity) */
+    reviewerModel?: string;
+    /** LLM model for verifier agent */
+    verifierModel?: string;
+    /** Whether to run verification (build/test) between rounds. Default: true */
+    verifyBetweenRounds: boolean;
+    /** Project path for file operations */
+    projectPath: string;
+    /** Tool executor for running tools (build, test, etc.) */
+    toolExecutor?: ToolExecutor;
+    /** BYOK config for LLM calls */
+    byokConfig?: BYOKConfig;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Maximum tokens per LLM call. Default: 16384 */
+    maxTokensPerCall: number;
+    /** Total token budget for the entire debate. Default: 200000 */
+    totalTokenBudget: number;
+}
+/** Role within the debate */
+export type DebateRole = "coder" | "reviewer" | "verifier";
+/** A single round of debate */
+export interface DebateRound {
+    /** Round number (1-based) */
+    round: number;
+    /** What the coder produced */
+    coderOutput: string;
+    /** Reviewer's critique text */
+    reviewerFeedback: string;
+    /** Structured issues found by reviewer */
+    issues: ReviewIssue[];
+    /** Coder's revised output after receiving feedback */
+    coderRevision?: string;
+    /** Verifier's result (if verification ran this round) */
+    verifierResult?: VerifierResult;
+}
+/** A structured issue found during review */
+export interface ReviewIssue {
+    /** How severe the issue is */
+    severity: "critical" | "major" | "minor" | "suggestion";
+    /** File path where the issue was found */
+    file?: string;
+    /** Line number of the issue */
+    line?: number;
+    /** Description of the issue */
+    description: string;
+    /** Suggested fix */
+    suggestion?: string;
+}
+/** Result from the verifier agent */
+export interface VerifierResult {
+    /** Whether overall verification passed */
+    passed: boolean;
+    /** Quality score 0-100 */
+    score: number;
+    /** Whether the build step passed */
+    buildPassed: boolean;
+    /** Whether the test step passed */
+    testsPassed: boolean;
+    /** Whether the security check passed */
+    securityPassed: boolean;
+    /** Detailed explanation */
+    details: string;
+}
+/** Final result of the entire debate session */
+export interface DebateResult {
+    /** Whether the debate concluded successfully */
+    success: boolean;
+    /** All rounds of the debate */
+    rounds: DebateRound[];
+    /** Final quality score */
+    finalScore: number;
+    /** Total tokens consumed across all roles */
+    totalTokensUsed: number;
+    /** Files that were changed during the debate */
+    changedFiles: string[];
+    /** Human-readable summary of the debate outcome */
+    summary: string;
+}
+/** Token usage tracked per role */
+interface RoleTokenUsage {
+    coder: {
+        input: number;
+        output: number;
+    };
+    reviewer: {
+        input: number;
+        output: number;
+    };
+    verifier: {
+        input: number;
+        output: number;
+    };
+}
+/** Events emitted by the DebateOrchestrator */
+export interface DebateOrchestratorEvents {
+    "debate:start": [payload: {
+        task: string;
+        maxRounds: number;
+    }];
+    "debate:round:start": [payload: {
+        round: number;
+    }];
+    "debate:round:end": [payload: {
+        round: number;
+        issueCount: number;
+    }];
+    "debate:coder": [payload: {
+        round: number;
+        output: string;
+    }];
+    "debate:reviewer": [payload: {
+        round: number;
+        issueCount: number;
+        hasCritical: boolean;
+    }];
+    "debate:revision": [payload: {
+        round: number;
+        output: string;
+    }];
+    "debate:verifier": [payload: {
+        round: number;
+        score: number;
+        passed: boolean;
+    }];
+    "debate:pass": [payload: {
+        round: number;
+        score: number;
+    }];
+    "debate:fail": [payload: {
+        finalScore: number;
+        reason: string;
+    }];
+    "debate:token_usage": [payload: {
+        role: DebateRole;
+        input: number;
+        output: number;
+    }];
+    "debate:abort": [payload: {
+        reason: string;
+    }];
+}
+/**
+ * DebateOrchestrator — Multi-agent debate loop for code quality improvement.
+ *
+ * Creates adversarial Coder/Reviewer/Verifier agents that check each other's work,
+ * significantly reducing hallucination and improving code quality.
+ *
+ * Uses EventEmitter for observability so callers can track progress in real-time.
+ */
+export declare class DebateOrchestrator extends EventEmitter {
+    private readonly config;
+    private rounds;
+    private totalTokens;
+    private readonly roleTokens;
+    private readonly changedFiles;
+    constructor(config: Partial<DebateConfig> & {
+        projectPath: string;
+    });
+    /**
+     * Run a debate session for a given task.
+     *
+     * The debate proceeds through rounds of Coder -> Reviewer -> Revision -> Verifier
+     * until the quality threshold is met or max rounds are exhausted.
+     *
+     * @param task - The coding task description
+     * @param context - Additional context (file contents, plan, etc.)
+     * @returns DebateResult with all rounds and final score
+     */
+    debate(task: string, context?: string): Promise<DebateResult>;
+    /**
+     * Coder Agent: Generates code to solve the task.
+     * Uses system prompt that emphasizes correctness, completeness, and clean code.
+     */
+    private runCoder;
+    /**
+     * Reviewer Agent: Critically reviews the coder's output.
+     * Uses system prompt that emphasizes finding bugs, security issues, edge cases.
+     * Returns structured feedback with severity levels.
+     */
+    private runReviewer;
+    /**
+     * Coder Agent (revision): Addresses reviewer feedback.
+     * Given the original code and reviewer issues, produces improved code.
+     */
+    private runCoderRevision;
+    /**
+     * Verifier Agent: Runs objective checks (build, test, security scan)
+     * and provides a holistic quality assessment via LLM.
+     */
+    private runVerifier;
+    /**
+     * Call the LLM with a system prompt and user message.
+     * Tracks token usage per role and total.
+     */
+    private callLLM;
+    /**
+     * Safely execute a tool via the tool executor.
+     * Returns a success/failure result, never throws.
+     */
+    private runToolSafe;
+    /**
+     * Parse the reviewer's JSON response into structured feedback + issues.
+     * Handles malformed JSON gracefully.
+     */
+    private parseReviewerResponse;
+    /**
+     * Parse raw issue objects into typed ReviewIssue[].
+     */
+    private parseIssues;
+    /**
+     * Parse the verifier's JSON response into a VerifierResult.
+     * Handles malformed JSON gracefully.
+     */
+    private parseVerifierResponse;
+    /**
+     * Extract JSON from a response that might contain markdown fencing or extra text.
+     */
+    private extractJson;
+    /**
+     * Build context for the next round, incorporating previous round's results.
+     */
+    private buildNextRoundContext;
+    /**
+     * Build the final DebateResult from all rounds and the final verification.
+     */
+    private buildResult;
+    /**
+     * Extract file paths mentioned in code output (e.g., "src/foo.ts").
+     */
+    private extractFilePaths;
+    /** Reset per-role token usage counters */
+    private resetRoleTokens;
+    /** Truncate text to a maximum length */
+    private truncate;
+    /** Get the current total token usage */
+    getTotalTokensUsed(): number;
+    /** Get token usage broken down by role */
+    getRoleTokenUsage(): Readonly<RoleTokenUsage>;
+    /** Get all rounds from the current/last debate */
+    getRounds(): readonly DebateRound[];
+    /** Get the current config */
+    getConfig(): Readonly<DebateConfig>;
+    /**
+     * Create a new DebateOrchestrator with the given config.
+     *
+     * @param config - Debate configuration (projectPath is required, rest have defaults)
+     * @returns A new DebateOrchestrator instance
+     */
+    static create(config: Partial<DebateConfig> & {
+        projectPath: string;
+    }): DebateOrchestrator;
+}
+export {};
+//# sourceMappingURL=debate-orchestrator.d.ts.map

package/dist/debate-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debate-orchestrator.d.ts","sourceRoot":"","sources":["../src/debate-orchestrator.ts"],"names":[],"mappings":"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"}