@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/arena/iterate/parse.js

@@ -1,123 +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.
- */
-/**
- * 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 function extractTag(text, tag) {
-    // First try the well-formed case (open + close).
-    const closed = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, "i");
-    const closedMatch = text.match(closed);
-    if (closedMatch)
-        return closedMatch[1].trim();
-    // Fall back to "open tag without close" — find <tag> and return content
-    // until the next opening tag of any kind, or EOF.
-    const opener = new RegExp(`<${tag}>`, "i");
-    const openMatch = opener.exec(text);
-    if (!openMatch)
-        return null;
-    const after = text.slice(openMatch.index + openMatch[0].length);
-    const nextTag = after.search(/<[a-z_][\w]*>/i);
-    const body = nextTag >= 0 ? after.slice(0, nextTag) : after;
-    return body.trim();
-}
-/** Parse merge response: extract v1 content + rationale. Falls back to whole text if markers are missing. */
-export function parseMergeResponse(text) {
-    const content = extractTag(text, "v1_content");
-    const rationale = extractTag(text, "merge_rationale");
-    if (content) {
-        return { content, rationale: rationale ?? undefined };
-    }
-    // Fallback: no markers — treat whole response as content (with a warning sentinel).
-    return { content: text.trim(), rationale: "[merge markers not found; using full response]" };
-}
-/** Parse revise response: extract content + meta JSON. */
-export function parseReviseResponse(text) {
-    const content = extractTag(text, "v_next_content");
-    const metaRaw = extractTag(text, "v_next_meta");
-    let meta = {};
-    if (metaRaw) {
-        // Strip surrounding code fences if present.
-        const cleaned = metaRaw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
-        try {
-            meta = JSON.parse(cleaned);
-        }
-        catch {
-            meta = { changelog: `[meta JSON parse failed; raw text below]\n${metaRaw}` };
-        }
-    }
-    return {
-        content: content ?? text.trim(),
-        meta,
-    };
-}
-/**
- * Parse critique JSON from an argue-phase response.
- * Tolerant: handles bare objects, fenced JSON, leading prose, trailing prose.
- */
-export function parseCritiquesResponse(text, criticName, idPrefix) {
-    const cleaned = text.replace(/^[^{[]*/, "").replace(/[^}\]]*$/, "").trim();
-    let parsed;
-    try {
-        parsed = JSON.parse(cleaned);
-    }
-    catch {
-        // Try to find the largest JSON object/array in the text.
-        const jsonMatch = text.match(/\{[\s\S]*\}|\[[\s\S]*\]/);
-        if (!jsonMatch)
-            return [];
-        try {
-            parsed = JSON.parse(jsonMatch[0]);
-        }
-        catch {
-            return [];
-        }
-    }
-    // Accept either {critiques: [...]} or [...] directly.
-    const arr = Array.isArray(parsed)
-        ? parsed
-        : parsed.critiques;
-    if (!Array.isArray(arr))
-        return [];
-    const out = [];
-    for (let i = 0; i < arr.length; i++) {
-        const c = arr[i];
-        if (!c.anchor || !c.comment)
-            continue;
-        let evidence;
-        if (Array.isArray(c.evidence)) {
-            evidence = c.evidence
-                .filter((e) => {
-                if (typeof e !== "object" || e === null)
-                    return false;
-                const obj = e;
-                return typeof obj.url === "string";
-            })
-                .map((e) => ({ url: e.url, snippet: e.snippet }));
-            if (evidence.length === 0)
-                evidence = undefined;
-        }
-        out.push({
-            id: `${idPrefix}-${criticName}-${i + 1}`,
-            critic: criticName,
-            anchor: String(c.anchor),
-            severity: c.severity ?? "minor",
-            category: c.category ?? "other",
-            comment: String(c.comment),
-            suggestion: c.suggestion ? String(c.suggestion) : undefined,
-            evidence,
-        });
-    }
-    return out;
-}

package/dist/arena/iterate/phases/argue.d.ts

@@ -1,22 +0,0 @@
-/**
- * Argue phase — critics read a draft and produce critiques in parallel.
- *
- * If `enableWebSearch` is on, each critic runs a tool-use loop and may call
- * web_search / web_fetch up to `maxArgueToolRounds` times before producing
- * the final critiques JSON. This is the deep-research path that catches
- * fabricated claims.
- */
-import type { ArenaParticipant } from "../../types.js";
-import type { FormatPack } from "../formats/index.js";
-import type { Critique, Draft, IterateProgressEvent, IterateSubject } from "../types.js";
-export declare function runArgueRound(args: {
-    subject: IterateSubject;
-    format: FormatPack;
-    draft: Draft;
-    critics: ArenaParticipant[];
-    round: number;
-    enableWebSearch?: boolean;
-    maxToolRounds?: number;
-    signal?: AbortSignal;
-    onProgress?: (e: IterateProgressEvent) => void;
-}): Promise<Critique[]>;

package/dist/arena/iterate/phases/argue.js

@@ -1,165 +0,0 @@
-/**
- * Argue phase — critics read a draft and produce critiques in parallel.
- *
- * If `enableWebSearch` is on, each critic runs a tool-use loop and may call
- * web_search / web_fetch up to `maxArgueToolRounds` times before producing
- * the final critiques JSON. This is the deep-research path that catches
- * fabricated claims.
- */
-import { createLLMClient } from "../../../llm/client-factory.js";
-import { logger } from "../../../logging/logger.js";
-import { parseCritiquesResponse } from "../parse.js";
-import { ITERATE_WEB_TOOLS, executeIterateWebTool, hasWebSearchProvider } from "../tools/web-tools.js";
-const DEFAULT_MAX_TOOL_ROUNDS = 8;
-export async function runArgueRound(args) {
-    const { subject, format, draft, critics, round, enableWebSearch, maxToolRounds, signal, onProgress } = args;
-    onProgress?.({ type: "argue_start", round, data: { criticCount: critics.length } });
-    // Web search is only useful if a provider is actually configured. Silently
-    // downgrade if not — log a warning so the user knows.
-    const wantWeb = Boolean(enableWebSearch);
-    const webAvailable = wantWeb && hasWebSearchProvider();
-    if (wantWeb && !webAvailable) {
-        logger.warn("arena.iterate.argue_web_unavailable", {
-            reason: "No SERPER_API_KEY / TAVILY_API_KEY / SEARXNG_URL configured",
-        });
-    }
-    const idPrefix = `r${round}`;
-    const tasks = critics.map(async (c) => {
-        signal?.throwIfAborted();
-        try {
-            if (webAvailable) {
-                return await argueWithToolLoop({
-                    critic: c,
-                    subject,
-                    format,
-                    draft,
-                    idPrefix,
-                    maxToolRounds: maxToolRounds ?? DEFAULT_MAX_TOOL_ROUNDS,
-                    signal,
-                });
-            }
-            return await argueSingleShot({ critic: c, subject, format, draft, idPrefix, signal });
-        }
-        catch (err) {
-            logger.warn("arena.iterate.argue_failed", {
-                round,
-                critic: c.name,
-                error: err.message,
-            });
-            return [];
-        }
-    });
-    const results = await Promise.all(tasks);
-    const allCritiques = results.flat();
-    onProgress?.({
-        type: "argue_done",
-        round,
-        data: { critiqueCount: allCritiques.length, webEnabled: webAvailable },
-    });
-    return allCritiques;
-}
-// ─── Single-shot argue (no tools) ─────────────────────────────────────
-async function argueSingleShot(args) {
-    const { critic, subject, format, draft, idPrefix, signal } = args;
-    const client = await createLLMClient(critic.llm, critic.clientDefaults);
-    const resp = await client.createMessage({
-        systemPrompt: format.argueSystem(format.format),
-        messages: [{ role: "user", content: format.argueUser(subject, draft) }],
-        tools: [],
-        signal,
-    });
-    const critiques = parseCritiquesResponse(resp.text, critic.name, idPrefix);
-    logger.info("arena.iterate.argue_singleshot", {
-        critic: critic.name,
-        critiqueCount: critiques.length,
-    });
-    return critiques;
-}
-// ─── Tool-use argue (with web search) ─────────────────────────────────
-async function argueWithToolLoop(args) {
-    const { critic, subject, format, draft, idPrefix, maxToolRounds, signal } = args;
-    const client = await createLLMClient(critic.llm, critic.clientDefaults);
-    const messages = [
-        { role: "user", content: format.argueUser(subject, draft) },
-    ];
-    let toolRounds = 0;
-    let finalText = "";
-    while (toolRounds < maxToolRounds) {
-        signal?.throwIfAborted();
-        const resp = await client.createMessage({
-            systemPrompt: format.argueSystem(format.format),
-            messages,
-            tools: ITERATE_WEB_TOOLS,
-            signal,
-        });
-        if (resp.text)
-            finalText = resp.text;
-        if (!resp.toolCalls || resp.toolCalls.length === 0) {
-            // Done — final response with critiques JSON.
-            break;
-        }
-        // Append assistant message with tool_use blocks
-        messages.push({
-            role: "assistant",
-            content: [
-                ...(resp.text ? [{ type: "text", text: resp.text }] : []),
-                ...resp.toolCalls.map((tc) => ({
-                    type: "tool_use",
-                    id: tc.id,
-                    name: tc.toolName,
-                    input: tc.args,
-                })),
-            ],
-        });
-        // Execute tools and append tool_result blocks
-        const toolResults = await Promise.all(resp.toolCalls.map(async (tc) => {
-            try {
-                const result = await executeIterateWebTool(tc.toolName, tc.args);
-                return { id: tc.id, content: result };
-            }
-            catch (err) {
-                return { id: tc.id, content: `Error: ${err.message}` };
-            }
-        }));
-        messages.push({
-            role: "user",
-            content: toolResults.map((tr) => ({
-                type: "tool_result",
-                tool_use_id: tr.id,
-                content: tr.content,
-            })),
-        });
-        toolRounds++;
-    }
-    // If we ran out of rounds with no final text, prod the model once more.
-    if (!finalText && toolRounds >= maxToolRounds) {
-        const resp = await client.createMessage({
-            systemPrompt: format.argueSystem(format.format),
-            messages: [
-                ...messages,
-                {
-                    role: "user",
-                    content: "You have used the maximum number of tool rounds. Produce your " +
-                        "critiques JSON now, based on what you have already gathered. " +
-                        "Do not request any more tools.",
-                },
-            ],
-            tools: [],
-            signal,
-        });
-        finalText = resp.text;
-    }
-    if (!finalText) {
-        // Both the tool loop and the force-conclude fallback produced no text
-        // (e.g. repeated max-token truncation). Log it — parseCritiquesResponse
-        // will just yield no critiques rather than silently parsing "".
-        logger.warn("arena.iterate.argue_empty_response", { critic: critic.name, toolRounds });
-    }
-    const critiques = parseCritiquesResponse(finalText, critic.name, idPrefix);
-    logger.info("arena.iterate.argue_toolloop", {
-        critic: critic.name,
-        critiqueCount: critiques.length,
-        toolRounds,
-    });
-    return critiques;
-}

package/dist/arena/iterate/phases/revise.d.ts

@@ -1,16 +0,0 @@
-/**
- * Revise phase — author rewrites the draft addressing critiques.
- */
-import type { ArenaParticipant } from "../../types.js";
-import type { FormatPack } from "../formats/index.js";
-import type { Critique, Draft, IterateProgressEvent, IterateSubject } from "../types.js";
-export declare function runRevise(args: {
-    subject: IterateSubject;
-    format: FormatPack;
-    previous: Draft;
-    critiques: Critique[];
-    author: ArenaParticipant;
-    minDraftLength: number;
-    signal?: AbortSignal;
-    onProgress?: (e: IterateProgressEvent) => void;
-}): Promise<Draft>;

package/dist/arena/iterate/phases/revise.js

@@ -1,62 +0,0 @@
-/**
- * Revise phase — author rewrites the draft addressing critiques.
- */
-import { createLLMClient } from "../../../llm/client-factory.js";
-import { logger } from "../../../logging/logger.js";
-import { parseReviseResponse } from "../parse.js";
-export async function runRevise(args) {
-    const { subject, format, previous, critiques, author, minDraftLength, signal, onProgress } = args;
-    onProgress?.({ type: "revise_start", round: previous.version + 1, participant: author.name });
-    const client = await createLLMClient(author.llm, author.clientDefaults);
-    const prompt = format.revisePrompt(subject, previous, critiques, minDraftLength);
-    const resp = await client.createMessage({
-        systemPrompt: prompt,
-        messages: [{ role: "user", content: `Produce v${previous.version + 1} now.` }],
-        tools: [],
-        maxTokens: 32_000,
-        signal,
-    });
-    const { content, meta } = parseReviseResponse(resp.text);
-    // Defensive: refuse to accept a revision that's drastically shorter than v(N) — that's
-    // usually the model collapsing into a summary rather than rewriting.
-    // Accept if shrinkage < 30% OR new content is still above the minimum length.
-    let acceptedContent = content;
-    const shrinkage = previous.content.length > 0
-        ? 1 - acceptedContent.length / previous.content.length
-        : 0;
-    if (shrinkage > 0.3 && acceptedContent.length < minDraftLength) {
-        logger.warn("arena.iterate.revise_too_short", {
-            version: previous.version + 1,
-            previousLength: previous.content.length,
-            newLength: acceptedContent.length,
-            minDraftLength,
-        });
-        // Don't retry automatically — keep going but flag in changelog.
-        meta.changelog =
-            `[WARNING: revision is ${Math.round(shrinkage * 100)}% shorter than v${previous.version}; the author may have summarized instead of rewriting]\n\n` +
-                (meta.changelog ?? "");
-    }
-    const next = {
-        version: previous.version + 1,
-        author: author.name,
-        format: format.format,
-        content: acceptedContent,
-        acceptedCritiques: meta.acceptedCritiques,
-        rejectedCritiques: meta.rejectedCritiques,
-        changelog: meta.changelog,
-    };
-    onProgress?.({
-        type: "revise_done",
-        round: next.version,
-        participant: author.name,
-        data: { length: acceptedContent.length, accepted: meta.acceptedCritiques?.length ?? 0 },
-    });
-    logger.info("arena.iterate.revise", {
-        version: next.version,
-        author: author.name,
-        length: acceptedContent.length,
-        accepted: meta.acceptedCritiques?.length ?? 0,
-        rejected: meta.rejectedCritiques?.length ?? 0,
-    });
-    return next;
-}

package/dist/arena/iterate/phases/tournament.d.ts

@@ -1,34 +0,0 @@
-/**
- * Tournament v1 phase — every participant writes a candidate, then the
- * author merges anonymized candidates into v1.
- */
-import type { ArenaParticipant } from "../../types.js";
-import type { FormatPack } from "../formats/index.js";
-import type { Draft, DraftCandidate, IterateProgressEvent, IterateSubject } from "../types.js";
-/** Run the v1 tournament: parallel candidate generation. */
-export declare function runTournamentCandidates(args: {
-    subject: IterateSubject;
-    format: FormatPack;
-    participants: ArenaParticipant[];
-    minDraftLength: number;
-    signal?: AbortSignal;
-    onProgress?: (e: IterateProgressEvent) => void;
-}): Promise<DraftCandidate[]>;
-/** Merge candidates into v1 using the author. */
-export declare function mergeCandidatesToV1(args: {
-    subject: IterateSubject;
-    format: FormatPack;
-    author: ArenaParticipant;
-    candidates: DraftCandidate[];
-    minDraftLength: number;
-    signal?: AbortSignal;
-    onProgress?: (e: IterateProgressEvent) => void;
-}): Promise<Draft>;
-/** Single-author v1 (tournament disabled) — author writes alone. */
-export declare function singleAuthorV1(args: {
-    subject: IterateSubject;
-    format: FormatPack;
-    author: ArenaParticipant;
-    minDraftLength: number;
-    signal?: AbortSignal;
-}): Promise<Draft>;

package/dist/arena/iterate/phases/tournament.js

@@ -1,113 +0,0 @@
-/**
- * Tournament v1 phase — every participant writes a candidate, then the
- * author merges anonymized candidates into v1.
- */
-import { createLLMClient } from "../../../llm/client-factory.js";
-import { logger } from "../../../logging/logger.js";
-import { parseMergeResponse } from "../parse.js";
-/** Run the v1 tournament: parallel candidate generation. */
-export async function runTournamentCandidates(args) {
-    const { subject, format, participants, minDraftLength, signal, onProgress } = args;
-    onProgress?.({ type: "v1_tournament_start", data: { count: participants.length } });
-    const tasks = participants.map(async (p, idx) => {
-        signal?.throwIfAborted();
-        const client = await createLLMClient(p.llm, p.clientDefaults);
-        const prompt = format.draftPrompt(subject, minDraftLength);
-        // Long-form generation needs a high output ceiling; the default 8k from
-        // LLMClientBase is too low for a substantive PRD or design doc and
-        // results in mid-sentence truncation that breaks downstream parsing.
-        const resp = await client.createMessage({
-            systemPrompt: prompt,
-            messages: [{ role: "user", content: `Write your draft now.` }],
-            tools: [],
-            maxTokens: 32_000,
-            signal,
-        });
-        const content = resp.text.trim();
-        const candidate = {
-            author: p.name,
-            anonymousLabel: `Draft ${String.fromCharCode(65 + idx)}`, // A, B, C...
-            content,
-        };
-        onProgress?.({
-            type: "v1_candidate_done",
-            participant: p.name,
-            data: { length: content.length, anonymousLabel: candidate.anonymousLabel },
-        });
-        logger.info("arena.iterate.v1_candidate", {
-            participant: p.name,
-            anonymousLabel: candidate.anonymousLabel,
-            length: content.length,
-        });
-        return candidate;
-    });
-    // Tolerate individual failures — we'd rather merge fewer drafts than abort.
-    const settled = await Promise.allSettled(tasks);
-    const candidates = [];
-    for (const s of settled) {
-        if (s.status === "fulfilled")
-            candidates.push(s.value);
-        else
-            logger.warn("arena.iterate.v1_candidate_failed", { error: s.reason?.message });
-    }
-    if (candidates.length === 0) {
-        throw new Error("All v1 tournament candidates failed");
-    }
-    // Shuffle so anonymous labels don't correlate with participants[] order.
-    for (let i = candidates.length - 1; i > 0; i--) {
-        const j = Math.floor(Math.random() * (i + 1));
-        [candidates[i], candidates[j]] = [candidates[j], candidates[i]];
-        candidates[i].anonymousLabel = `Draft ${String.fromCharCode(65 + i)}`;
-    }
-    candidates[0].anonymousLabel = `Draft A`;
-    return candidates;
-}
-/** Merge candidates into v1 using the author. */
-export async function mergeCandidatesToV1(args) {
-    const { subject, format, author, candidates, minDraftLength, signal, onProgress } = args;
-    onProgress?.({ type: "v1_merge_start", participant: author.name });
-    const client = await createLLMClient(author.llm, author.clientDefaults);
-    const prompt = format.mergePrompt(subject, candidates, minDraftLength);
-    const resp = await client.createMessage({
-        systemPrompt: prompt,
-        messages: [{ role: "user", content: `Produce v1 now.` }],
-        tools: [],
-        maxTokens: 32_000,
-        signal,
-    });
-    const { content, rationale } = parseMergeResponse(resp.text);
-    const draft = {
-        version: 1,
-        author: author.name,
-        format: format.format,
-        content,
-        draftCandidates: candidates,
-        mergeRationale: rationale,
-    };
-    onProgress?.({ type: "v1_merge_done", participant: author.name, data: { length: content.length } });
-    logger.info("arena.iterate.v1_merge", {
-        author: author.name,
-        candidateCount: candidates.length,
-        length: content.length,
-    });
-    return draft;
-}
-/** Single-author v1 (tournament disabled) — author writes alone. */
-export async function singleAuthorV1(args) {
-    const { subject, format, author, minDraftLength, signal } = args;
-    const client = await createLLMClient(author.llm, author.clientDefaults);
-    const prompt = format.draftPrompt(subject, minDraftLength);
-    const resp = await client.createMessage({
-        systemPrompt: prompt,
-        messages: [{ role: "user", content: `Write your draft now.` }],
-        tools: [],
-        maxTokens: 32_000,
-        signal,
-    });
-    return {
-        version: 1,
-        author: author.name,
-        format: format.format,
-        content: resp.text.trim(),
-    };
-}

package/dist/arena/iterate/tools/web-tools.d.ts

@@ -1,13 +0,0 @@
-/**
- * Web tools for arena iterate critics — fabrication detection support.
- *
- * Wraps the existing builtin webSearchTool / webFetchTool so critics can
- * verify factual claims during the argue phase.
- */
-import type { ToolDefinition } from "../../../types.js";
-export declare const webSearchToolDef: ToolDefinition;
-export declare const webFetchToolDef: ToolDefinition;
-export declare const ITERATE_WEB_TOOLS: ToolDefinition[];
-export declare function executeIterateWebTool(toolName: string, args: Record<string, unknown>): Promise<string>;
-/** Probe env to determine if any web-search provider is configured. */
-export declare function hasWebSearchProvider(): boolean;

package/dist/arena/iterate/tools/web-tools.js

@@ -1,54 +0,0 @@
-/**
- * Web tools for arena iterate critics — fabrication detection support.
- *
- * Wraps the existing builtin webSearchTool / webFetchTool so critics can
- * verify factual claims during the argue phase.
- */
-import { webSearchTool } from "../../../tool-system/builtin/web-search.js";
-import { webFetchTool } from "../../../tool-system/builtin/web-fetch.js";
-export const webSearchToolDef = {
-    name: "web_search",
-    description: "Search the web (Google via Serper / Tavily / SearXNG depending on env). " +
-        "Use this to verify any specific number, citation, URL, library version, " +
-        "API name, or external claim made in the draft you are reviewing. " +
-        "If a claim cannot be verified by web_search, mark it as a fabrication " +
-        "critique with severity = blocker.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            query: { type: "string", description: "Search query (English usually works best)." },
-            num_results: { type: "number", description: "Default 5, max 20." },
-        },
-        required: ["query"],
-    },
-};
-export const webFetchToolDef = {
-    name: "web_fetch",
-    description: "Fetch a URL and return its text content (HTML stripped). Use after " +
-        "web_search to read the actual page content of a search result and " +
-        "confirm a specific claim, version number, or quoted figure.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            url: { type: "string", description: "Full http(s) URL to fetch." },
-            max_length: { type: "number", description: "Default 50000 characters." },
-        },
-        required: ["url"],
-    },
-};
-export const ITERATE_WEB_TOOLS = [webSearchToolDef, webFetchToolDef];
-export async function executeIterateWebTool(toolName, args) {
-    if (toolName === "web_search") {
-        return webSearchTool(args);
-    }
-    if (toolName === "web_fetch") {
-        return webFetchTool(args);
-    }
-    return `Error: unknown tool "${toolName}"`;
-}
-/** Probe env to determine if any web-search provider is configured. */
-export function hasWebSearchProvider() {
-    return Boolean(process.env.SERPER_API_KEY ||
-        process.env.TAVILY_API_KEY ||
-        process.env.SEARXNG_URL);
-}