@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/arena/iterate/formats/index.js

@@ -1,283 +0,0 @@
-/**
- * Format packs — prompt templates for code vs document iteration.
- *
- * Each format provides four prompt builders:
- *   - draftPrompt:    used in tournament v1 (every participant writes a candidate)
- *   - mergePrompt:    used in v1 merge (author reads anonymized candidates → v1)
- *   - argueSystem:    system prompt for critics
- *   - argueUser:      user prompt that wraps the current draft for critique
- *   - revisePrompt:   used to produce v(N+1) given v(N) + critiques
- */
-const COMMON_DRAFT_RULES = `
-Hard rules:
-- Output the FULL artifact, not a sketch or outline.
-- No "...", "(continued)", "see above", "TBD", or placeholders.
-- Don't pad with filler. Every section must carry information.
-- Length is a floor, not a target — go beyond it if the topic warrants.
-
-Factual discipline (CRITICAL — fabrication = blocker-level defect):
-- Do NOT invent specific numbers, percentages, dollar amounts, market sizes,
-  user-research counts, or "industry averages" you cannot verify.
-- Do NOT invent URLs, report IDs, document numbers, citation references.
-- Do NOT invent named people, companies, or product code-names.
-- For unknowable specifics, write a placeholder with the exact form:
-    [需调研: 具体说明]    e.g.  "[需调研: 实际行业流失率基准]"
-    [TBD: short reason]   e.g.  "[TBD: confirm Stripe rate limits]"
-  These placeholders are EXPECTED. Reviewers will not fault you for them.
-- General qualitative claims are fine ("annual growth typically in the
-  double digits"); specific numbers without a verifiable source are NOT.
-- If you have web-search tools available, USE them before stating any
-  specific number or citing any source.
-`;
-function formatCritiquesForPrompt(critiques) {
-    return critiques
-        .map((c, i) => `[${i + 1}] id=${c.id} severity=${c.severity} category=${c.category} from=${c.critic}\n` +
-        `    anchor: "${c.anchor}"\n` +
-        `    comment: ${c.comment}` +
-        (c.suggestion ? `\n    suggestion: ${c.suggestion}` : ""))
-        .join("\n\n");
-}
-// ─── Code format ────────────────────────────────────────────────
-export const codeFormat = {
-    format: "code",
-    draftPrompt(subject, minLength) {
-        return `You are writing a complete code artifact for the following task.
-
-Task: ${subject.label}
-Description: ${subject.description}
-${subject.sources?.length ? `Source files for context: ${subject.sources.join(", ")}` : ""}
-
-This draft will compete with drafts from other participants in a tournament round.
-A merger will then read all drafts (anonymously) and pick the strongest parts.
-Make your draft strong, distinct, complete, and self-contained.
-
-Output requirements:
-- Compile-ready code in the appropriate language (infer from sources / description).
-- Include tests if behavior is non-trivial.
-- Inline comments only where the WHY is non-obvious — names should explain WHAT.
-- At least ${minLength} characters of substantive code (filler will be cut by the merger).
-${COMMON_DRAFT_RULES}`;
-    },
-    mergePrompt(subject, candidates, minLength) {
-        const blocks = candidates
-            .map((c) => `--- ${c.anonymousLabel} ---\n${c.content}\n--- end ${c.anonymousLabel} ---`)
-            .join("\n\n");
-        return `Below are ${candidates.length} draft solutions for the same task, presented anonymously.
-Your job: produce a single v1 by merging the strongest parts of each.
-
-Task: ${subject.label}
-Description: ${subject.description}
-
-${blocks}
-
-Merging rules:
-- For each section / function / module, pick the strongest version OR write a new one inspired by the best ideas.
-- Inline EVERYTHING. Do not write "see Draft B for the auth helper" — copy the auth helper in.
-- v1 must be COMPLETE and at least ${minLength} characters of substantive code.
-- After the code, output a 'mergeRationale' section: one short paragraph per major decision, "From Draft X I took ____, because ____. I rejected ____ because ____."
-
-Output format (literally — these markers will be parsed):
-
-<v1_content>
-{full code goes here}
-</v1_content>
-
-<merge_rationale>
-{your rationale here}
-</merge_rationale>`;
-    },
-    argueSystem() {
-        return `You are reviewing a code artifact. Find every meaningful issue.
-
-You may have access to a web_search tool — USE IT to verify any specific
-claim, library version, API behavior, or external reference made in the
-draft before deciding whether it's a fabrication.
-
-For each issue:
-- "anchor": quote 5-15 words verbatim from the draft to locate the issue.
-- "severity": "blocker" (must fix), "major" (should fix), "minor" (nice to fix), "nit" (style), or "praise" (good — don't gut this).
-- "category": "correctness" | "completeness" | "clarity" | "evidence" | "structure" | "style" | "fabrication" | "other".
-- "comment": what's wrong and what you'd do. If you used web_search, cite the URL.
-- "suggestion": optional concrete fix.
-- "evidence": optional array of {url, snippet} pairs supporting your critique.
-
-FABRICATION DETECTION (top priority):
-Any specific number, citation, URL, version string, API endpoint, library
-function, or named entity that you cannot verify is a "fabrication"
-critique with severity = "blocker". Be especially suspicious of:
-- "Industry average is X%" / "Surveys show N=..."
-- Documentation URLs with suspiciously generic paths
-- Library/API names that "sound right" but you can't confirm exist
-
-Aim for 8-20 critiques. Include PRAISE for parts that are genuinely good — this prevents the author from accidentally gutting them in the next revision.
-
-Output strictly as JSON: {"critiques": [{...}, ...]}`;
-    },
-    argueUser(subject, draft, lens) {
-        return `Task: ${subject.label}
-${lens ? `Review lens: ${lens}\n` : ""}
-Current draft (v${draft.version}, by ${draft.author}):
-
-${draft.content}
-
-Now produce your critiques as JSON.`;
-    },
-    revisePrompt(subject, previous, critiques, minLength) {
-        return `You wrote v${previous.version}. Critics raised ${critiques.length} points.
-Rewrite the artifact as v${previous.version + 1}.
-
-Task: ${subject.label}
-Description: ${subject.description}
-
-Current draft (v${previous.version}):
-${previous.content}
-
-Critiques:
-${formatCritiquesForPrompt(critiques)}
-
-Rules:
-- ADDRESS every blocker and major. You may disagree, but say why in changelog.
-- Preserve PRAISE-tagged parts unless a later critique contradicts.
-- Output the COMPLETE new artifact (at least ${minLength} chars), not a diff.
-- After the code, output a JSON block:
-
-<v_next_content>
-{full code goes here}
-</v_next_content>
-
-<v_next_meta>
-{
-  "acceptedCritiques": ["id1", "id2", ...],
-  "rejectedCritiques": [{"id": "id3", "reason": "..."}, ...],
-  "changelog": "what changed and why, in 1-3 short paragraphs"
-}
-</v_next_meta>`;
-    },
-};
-// ─── Document format ────────────────────────────────────────────
-export const documentFormat = {
-    format: "document",
-    draftPrompt(subject, minLength) {
-        return `You are writing a complete long-form document for the following subject.
-
-Subject: ${subject.label}
-Description: ${subject.description}
-${subject.sources?.length ? `Reference materials: ${subject.sources.join(", ")}` : ""}
-
-This draft will compete with drafts from other participants in a tournament round.
-A merger will then read all drafts (anonymously) and pick the strongest parts.
-Make your draft strong, distinct, complete, and self-contained.
-
-Document requirements:
-- Use clear hierarchical structure (## sections, ### subsections).
-- Every section must carry concrete information: examples, comparisons, trade-offs, numbers.
-- Cite sources inline with [n] footnotes when you make factual claims.
-- At least ${minLength} characters of substantive prose (filler will be cut by the merger).
-${COMMON_DRAFT_RULES}`;
-    },
-    mergePrompt(subject, candidates, minLength) {
-        const blocks = candidates
-            .map((c) => `--- ${c.anonymousLabel} ---\n${c.content}\n--- end ${c.anonymousLabel} ---`)
-            .join("\n\n");
-        return `Below are ${candidates.length} draft documents for the same subject, presented anonymously.
-Your job: produce a single v1 markdown document by merging the strongest parts.
-
-Subject: ${subject.label}
-Description: ${subject.description}
-
-${blocks}
-
-Merging rules:
-- Pick the strongest section from each draft, OR write a new section that combines their best ideas.
-- DO NOT write "see Draft B for ____" — inline everything.
-- The final v1 must be COMPLETE and at least ${minLength} characters.
-- Maintain coherent voice and consistent structure across sections.
-
-Output format (literally — these markers will be parsed):
-
-<v1_content>
-{full markdown document}
-</v1_content>
-
-<merge_rationale>
-{1-3 short paragraphs: from which draft you took which section, why; what you rejected, why}
-</merge_rationale>`;
-    },
-    argueSystem() {
-        return `You are reviewing a long-form document. Find every meaningful issue.
-
-You may have access to a web_search tool — USE IT to verify any specific
-number, citation, market figure, named survey, or external reference
-before deciding whether it's a fabrication.
-
-For each issue:
-- "anchor": quote 5-15 words verbatim from the document to locate the issue.
-- "severity": "blocker" | "major" | "minor" | "nit" | "praise".
-- "category": "correctness" | "completeness" | "clarity" | "evidence" | "structure" | "style" | "fabrication" | "other".
-- "comment": what's wrong / missing / weak. If you used web_search, cite the URL.
-- "suggestion": optional concrete fix or content to add.
-- "evidence": optional array of {url, snippet} pairs supporting your critique.
-
-FABRICATION DETECTION (top priority):
-The document is far more likely to fail because of fabricated facts than
-because of missing sections. Treat every specific number / report ID /
-URL / dollar figure / "industry average" / named survey as suspect until
-verified. Mark as severity = "blocker" if:
-- The number cannot be found via web_search.
-- The cited URL doesn't resolve to the claimed source.
-- The "report ID" / "document number" appears made up.
-- The named survey / interviewee count cannot be traced.
-A draft full of citations that don't check out is worse than a draft
-that honestly writes "[需调研: ...]". Reward the latter.
-
-Aim for 8-20 critiques. Don't be polite — depth, missing sections, weak claims, and structural issues matter more than typos. Include PRAISE for genuinely strong parts so the author doesn't gut them on revision.
-
-Output strictly as JSON: {"critiques": [{...}, ...]}`;
-    },
-    argueUser(subject, draft, lens) {
-        return `Subject: ${subject.label}
-${lens ? `Review lens: ${lens}\n` : ""}
-Current document (v${draft.version}, by ${draft.author}):
-
-${draft.content}
-
-Now produce your critiques as JSON.`;
-    },
-    revisePrompt(subject, previous, critiques, minLength) {
-        return `You wrote v${previous.version}. Critics raised ${critiques.length} points.
-Rewrite the document as v${previous.version + 1}.
-
-Subject: ${subject.label}
-Description: ${subject.description}
-
-Current document (v${previous.version}):
-${previous.content}
-
-Critiques:
-${formatCritiquesForPrompt(critiques)}
-
-Rules:
-- ADDRESS every blocker and major. You may disagree, but say why in changelog.
-- Preserve PRAISE-tagged parts.
-- Expand sections that were called out as thin / missing examples / lacking evidence.
-- Output the COMPLETE new document (at least ${minLength} chars).
-
-Output format (literally — these markers will be parsed):
-
-<v_next_content>
-{full markdown document}
-</v_next_content>
-
-<v_next_meta>
-{
-  "acceptedCritiques": ["id1", "id2", ...],
-  "rejectedCritiques": [{"id": "id3", "reason": "..."}, ...],
-  "changelog": "what changed and why, in 1-3 short paragraphs"
-}
-</v_next_meta>`;
-    },
-};
-// ─── Selector ───────────────────────────────────────────────────
-export function getFormat(format) {
-    return format === "code" ? codeFormat : documentFormat;
-}

package/dist/arena/iterate/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * Arena Iterate — multi-model authoring loop.
- *
- * Public API for the iterate mode.
- */
-export { IterativeArena } from "./iterative-arena.js";
-export { defaultConvergence, diffRatio } from "./convergence.js";
-export { codeFormat, documentFormat, getFormat } from "./formats/index.js";
-export type { FormatPack } from "./formats/index.js";
-export type { AuthorRotation, CheckpointAction, CheckpointContext, CheckpointFn, ConvergenceSignal, Critique, CritiqueCategory, CritiqueEvidence, CritiqueSeverity, Draft, DraftCandidate, IterateConfig, IterateFormat, IterateProgressEvent, IterateResult, IterateSubject, Round, StoppedReason, } from "./types.js";
-export { ITERATE_WEB_TOOLS, hasWebSearchProvider } from "./tools/web-tools.js";

package/dist/arena/iterate/index.js

@@ -1,9 +0,0 @@
-/**
- * Arena Iterate — multi-model authoring loop.
- *
- * Public API for the iterate mode.
- */
-export { IterativeArena } from "./iterative-arena.js";
-export { defaultConvergence, diffRatio } from "./convergence.js";
-export { codeFormat, documentFormat, getFormat } from "./formats/index.js";
-export { ITERATE_WEB_TOOLS, hasWebSearchProvider } from "./tools/web-tools.js";

package/dist/arena/iterate/iterative-arena.d.ts

@@ -1,23 +0,0 @@
-/**
- * IterativeArena — multi-model authoring loop.
- *
- * Pipeline:
- *   1. v1: tournament (default) or single-author
- *   2. for each round 2..maxRounds:
- *        a. argue (parallel critics)
- *        b. checkpoint (optional human pause)
- *        c. convergence check
- *        d. if not converged: revise → next round
- *   3. final draft = last round's draft
- */
-import type { IterateConfig, IterateResult } from "./types.js";
-export declare class IterativeArena {
-    private readonly config;
-    constructor(config: IterateConfig);
-    run(): Promise<IterateResult>;
-    /** Critics for a given round = pool minus current author (so author isn't critiquing self). */
-    private criticsForRound;
-    private checkConvergence;
-    private pickNextAuthor;
-    private finalize;
-}

package/dist/arena/iterate/iterative-arena.js

@@ -1,237 +0,0 @@
-/**
- * IterativeArena — multi-model authoring loop.
- *
- * Pipeline:
- *   1. v1: tournament (default) or single-author
- *   2. for each round 2..maxRounds:
- *        a. argue (parallel critics)
- *        b. checkpoint (optional human pause)
- *        c. convergence check
- *        d. if not converged: revise → next round
- *   3. final draft = last round's draft
- */
-import { logger } from "../../logging/logger.js";
-import { defaultConvergence, diffRatio } from "./convergence.js";
-import { getFormat } from "./formats/index.js";
-import { runArgueRound } from "./phases/argue.js";
-import { runRevise } from "./phases/revise.js";
-import { mergeCandidatesToV1, runTournamentCandidates, singleAuthorV1 } from "./phases/tournament.js";
-const DEFAULT_MAX_ROUNDS = 5;
-export class IterativeArena {
-    config;
-    constructor(config) {
-        if (!config.author) {
-            throw new Error("IterativeArena requires an `author` participant");
-        }
-        if (!config.critics || config.critics.length === 0) {
-            throw new Error("IterativeArena requires at least 1 critic");
-        }
-        const allNames = [config.author.name, ...config.critics.map((c) => c.name)];
-        if (new Set(allNames).size !== allNames.length) {
-            throw new Error("Author and critics must have unique names");
-        }
-        this.config = config;
-    }
-    async run() {
-        const start = Date.now();
-        const { config } = this;
-        const format = getFormat(config.format);
-        const maxRounds = config.maxRounds ?? DEFAULT_MAX_ROUNDS;
-        const minDraftLength = config.minDraftLength ?? (config.format === "code" ? 200 : 800);
-        const signal = config.signal;
-        const rounds = [];
-        // ─── Phase: v1 ────────────────────────────────────────────
-        let currentDraft;
-        try {
-            if ((config.v1Strategy ?? "tournament") === "tournament") {
-                const candidates = await runTournamentCandidates({
-                    subject: config.subject,
-                    format,
-                    participants: [config.author, ...config.critics],
-                    minDraftLength,
-                    signal,
-                    onProgress: config.onProgress,
-                });
-                currentDraft = await mergeCandidatesToV1({
-                    subject: config.subject,
-                    format,
-                    author: config.author,
-                    candidates,
-                    minDraftLength,
-                    signal,
-                    onProgress: config.onProgress,
-                });
-            }
-            else {
-                currentDraft = await singleAuthorV1({
-                    subject: config.subject,
-                    format,
-                    author: config.author,
-                    minDraftLength,
-                    signal,
-                });
-            }
-        }
-        catch (err) {
-            logger.error("arena.iterate.v1_failed", { error: err.message });
-            throw err;
-        }
-        // Author rotation state. We pick the next author from the pool of
-        // {author, critics} according to the rotation policy.
-        let currentAuthor = config.author;
-        const pool = [config.author, ...config.critics];
-        // ─── Phase: argue/revise loop ────────────────────────────
-        let previousDraft;
-        for (let r = 1; r <= maxRounds; r++) {
-            signal?.throwIfAborted();
-            // Argue against the current draft.
-            const critiques = await runArgueRound({
-                subject: config.subject,
-                format,
-                draft: currentDraft,
-                critics: this.criticsForRound(r),
-                round: r,
-                enableWebSearch: config.enableWebSearch,
-                maxToolRounds: config.maxArgueToolRounds,
-                signal,
-                onProgress: config.onProgress,
-            });
-            // Convergence check.
-            const convergence = this.checkConvergence({
-                round: r,
-                critiques,
-                draft: currentDraft,
-                previousDraft,
-            });
-            const round = {
-                round: r,
-                draft: currentDraft,
-                critiques,
-                convergence,
-            };
-            // Optional human checkpoint.
-            let userAction;
-            if (config.humanCheckpoint) {
-                config.onProgress?.({ type: "checkpoint_pause", round: r });
-                userAction = await config.humanCheckpoint({
-                    round: r,
-                    draft: currentDraft,
-                    critiques,
-                    convergence,
-                });
-            }
-            rounds.push(round);
-            config.onProgress?.({
-                type: "round_done",
-                round: r,
-                data: {
-                    critiques: critiques.length,
-                    shouldStop: convergence.shouldStop,
-                    userAction,
-                },
-            });
-            if (userAction === "stop") {
-                return this.finalize(rounds, "user_stop", start);
-            }
-            if (userAction !== "force-continue" && convergence.shouldStop) {
-                return this.finalize(rounds, "converged", start);
-            }
-            if (r === maxRounds) {
-                return this.finalize(rounds, "max_rounds", start);
-            }
-            // Revise → v(r+1)
-            previousDraft = currentDraft;
-            currentAuthor = this.pickNextAuthor(currentAuthor, critiques, pool, r);
-            currentDraft = await runRevise({
-                subject: config.subject,
-                format,
-                previous: previousDraft,
-                critiques,
-                author: currentAuthor,
-                minDraftLength,
-                signal,
-                onProgress: config.onProgress,
-            });
-        }
-        return this.finalize(rounds, "max_rounds", start);
-    }
-    /** Critics for a given round = pool minus current author (so author isn't critiquing self). */
-    criticsForRound(_round) {
-        return this.config.critics;
-    }
-    checkConvergence(args) {
-        if (this.config.convergenceStrategy && this.config.convergenceStrategy !== "default") {
-            const stop = this.config.convergenceStrategy(args);
-            const blockerCount = args.critiques.filter((c) => c.severity === "blocker").length;
-            const majorCount = args.critiques.filter((c) => c.severity === "major").length;
-            const diffFromPrevious = args.previousDraft
-                ? diffRatio(args.previousDraft.content, args.draft.content)
-                : 1;
-            return {
-                blockerCount,
-                majorCount,
-                totalCritiques: args.critiques.length,
-                diffFromPrevious,
-                shouldStop: stop,
-                reason: stop ? "all_minor_or_praise" : "running",
-            };
-        }
-        return defaultConvergence(args);
-    }
-    pickNextAuthor(current, critiques, pool, round) {
-        const policy = this.config.authorRotation ?? "fixed";
-        if (policy === "fixed")
-            return this.config.author;
-        if (policy === "round-robin") {
-            const idx = round % pool.length;
-            return pool[idx];
-        }
-        if (policy === "best-critic") {
-            // Score critics by sum of severities they raised; tie → most critiques.
-            const sevWeight = {
-                blocker: 5, major: 3, minor: 1, nit: 0.5, praise: 0,
-            };
-            const scores = new Map();
-            for (const c of critiques) {
-                scores.set(c.critic, (scores.get(c.critic) ?? 0) + (sevWeight[c.severity] ?? 0));
-            }
-            let best = current.name;
-            let bestScore = -1;
-            for (const [name, score] of scores) {
-                if (score > bestScore) {
-                    bestScore = score;
-                    best = name;
-                }
-            }
-            const winner = pool.find((p) => p.name === best);
-            return winner ?? current;
-        }
-        return current;
-    }
-    finalize(rounds, stoppedAt, start) {
-        const finalDraft = rounds.at(-1).draft;
-        const result = {
-            subject: this.config.subject,
-            format: this.config.format,
-            rounds,
-            finalDraft,
-            stoppedAt,
-            durationMs: Date.now() - start,
-        };
-        this.config.onProgress?.({
-            type: "iterate_complete",
-            data: {
-                stoppedAt,
-                rounds: rounds.length,
-                finalLength: finalDraft.content.length,
-            },
-        });
-        logger.info("arena.iterate.complete", {
-            stoppedAt,
-            rounds: rounds.length,
-            finalVersion: finalDraft.version,
-            finalLength: finalDraft.content.length,
-        });
-        return result;
-    }
-}

package/dist/arena/iterate/parse.d.ts

@@ -1,42 +0,0 @@
-/**
- * Parsing helpers for LLM responses in iterate mode.
- *
- * We use literal XML-ish markers (<v1_content>…</v1_content>) instead of
- * pure JSON because LLMs are far more reliable at "write 5000 chars of
- * markdown then a small JSON block at the end" than at producing one
- * giant well-formed JSON document with a 5000-char string field.
- */
-import type { Critique } from "./types.js";
-/**
- * Extract content between `<tag>` and `</tag>`.
- *
- * Forgiving in two ways:
- *  - Case-insensitive on the tag name.
- *  - If the closing tag is missing (LLM hit max_tokens mid-output), we still
- *    return everything after the opening tag, stopping at the next sibling
- *    tag (e.g. the `<merge_rationale>` block) if present, otherwise EOF.
- */
-export declare function extractTag(text: string, tag: string): string | null;
-/** Parse merge response: extract v1 content + rationale. Falls back to whole text if markers are missing. */
-export declare function parseMergeResponse(text: string): {
-    content: string;
-    rationale?: string;
-};
-export interface ReviseMeta {
-    acceptedCritiques?: string[];
-    rejectedCritiques?: Array<{
-        id: string;
-        reason: string;
-    }>;
-    changelog?: string;
-}
-/** Parse revise response: extract content + meta JSON. */
-export declare function parseReviseResponse(text: string): {
-    content: string;
-    meta: ReviseMeta;
-};
-/**
- * Parse critique JSON from an argue-phase response.
- * Tolerant: handles bare objects, fenced JSON, leading prose, trailing prose.
- */
-export declare function parseCritiquesResponse(text: string, criticName: string, idPrefix: string): Critique[];