@cjhyy/code-shell-arena 0.8.0

package/dist/iterate/convergence.js

@@ -0,0 +1,103 @@
+/**
+ * Convergence detection — when has the draft stabilized enough to stop?
+ */
+/**
+ * Cheap O(n) approximation of "how different is new vs old".
+ * Returns 0..1 where 0 = identical, 1 = completely different.
+ *
+ * Uses character-trigram Jaccard distance — fast, good enough for "is the
+ * author actually changing anything substantial?".
+ */
+export function diffRatio(a, b) {
+    if (a === b)
+        return 0;
+    if (!a || !b)
+        return 1;
+    const trigrams = (s) => {
+        const out = new Set();
+        for (let i = 0; i < s.length - 2; i++)
+            out.add(s.slice(i, i + 3));
+        return out;
+    };
+    const A = trigrams(a);
+    const B = trigrams(b);
+    let inter = 0;
+    for (const t of A)
+        if (B.has(t))
+            inter++;
+    const union = A.size + B.size - inter;
+    if (union === 0)
+        return 0;
+    const jaccard = inter / union; // similarity
+    return 1 - jaccard;
+}
+/**
+ * Default convergence rule:
+ *   stop if blockers == 0 AND
+ *     (all critiques are minor/nit/praise OR diff < 5% from last version)
+ *
+ * Round 1 never converges (need at least one revision pass).
+ */
+export function defaultConvergence(args) {
+    const { round, critiques, draft, previousDraft } = args;
+    const blockerCount = critiques.filter((c) => c.severity === "blocker").length;
+    const majorCount = critiques.filter((c) => c.severity === "major").length;
+    const totalCritiques = critiques.length;
+    const diffFromPrevious = previousDraft ? diffRatio(previousDraft.content, draft.content) : 1;
+    // Round 1 (the v1) — always do at least one revision pass, never converge here.
+    if (round === 1) {
+        return {
+            blockerCount,
+            majorCount,
+            totalCritiques,
+            diffFromPrevious,
+            shouldStop: false,
+            reason: "running",
+        };
+    }
+    // Special case: zero critiques is almost always a parsing/timeout failure
+    // on the critic side, NOT a sign of convergence. Treat as "running" so
+    // the next round has a chance — the loop will naturally stop at maxRounds.
+    if (totalCritiques === 0) {
+        return {
+            blockerCount,
+            majorCount,
+            totalCritiques,
+            diffFromPrevious,
+            shouldStop: false,
+            reason: "running",
+        };
+    }
+    // Hard floor: no blockers AND no majors → all that's left is polish.
+    // Require at least 3 critiques so a single low-effort response can't
+    // declare false convergence.
+    if (blockerCount === 0 && majorCount === 0 && totalCritiques >= 3) {
+        return {
+            blockerCount,
+            majorCount,
+            totalCritiques,
+            diffFromPrevious,
+            shouldStop: true,
+            reason: "all_minor_or_praise",
+        };
+    }
+    // Soft floor: no blockers AND draft barely moved → author is stuck or done.
+    if (blockerCount === 0 && diffFromPrevious < 0.05) {
+        return {
+            blockerCount,
+            majorCount,
+            totalCritiques,
+            diffFromPrevious,
+            shouldStop: true,
+            reason: "blockers_zero_and_stable",
+        };
+    }
+    return {
+        blockerCount,
+        majorCount,
+        totalCritiques,
+        diffFromPrevious,
+        shouldStop: false,
+        reason: "running",
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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
+ */
+import type { Critique, Draft, DraftCandidate, IterateFormat, IterateSubject } from "../types.js";
+export interface FormatPack {
+    format: IterateFormat;
+    draftPrompt(subject: IterateSubject, minLength: number): string;
+    mergePrompt(subject: IterateSubject, candidates: DraftCandidate[], minLength: number): string;
+    argueSystem(format: IterateFormat): string;
+    argueUser(subject: IterateSubject, draft: Draft, lens?: string): string;
+    revisePrompt(subject: IterateSubject, previous: Draft, critiques: Critique[], minLength: number): string;
+}
+export declare const codeFormat: FormatPack;
+export declare const documentFormat: FormatPack;
+export declare function getFormat(format: IterateFormat): FormatPack;

package/dist/iterate/formats/index.js

@@ -0,0 +1,283 @@
+/**
+ * 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/iterate/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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/iterate/index.js

@@ -0,0 +1,9 @@
+/**
+ * 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/iterate/iterative-arena.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 round = the whole pool minus whoever wrote the draft under
+     * review, so nobody critiques their own text.
+     *
+     * This used to return `config.critics` verbatim, ignoring rotation. Once
+     * `round-robin`/`best-critic` promoted critic B to author, B kept reviewing
+     * the draft B had just written, while the original author A never entered the
+     * critic pool at all — the exact opposite of the intent documented here.
+     */
+    private criticsForRound;
+    private checkConvergence;
+    private pickNextAuthor;
+    private finalize;
+}