@scira/cli 0.1.0

package/dist/providers/llm/gateway.js

@@ -0,0 +1,64 @@
+import { generateText, gateway } from "ai";
+import { getLanguageModel, requireLlmKeys, defaultModelFor } from "./registry.js";
+async function fetchModelsRaw() {
+    const headers = {};
+    if (process.env.AI_GATEWAY_API_KEY) {
+        headers.Authorization = `Bearer ${process.env.AI_GATEWAY_API_KEY}`;
+    }
+    const response = await fetch("https://ai-gateway.vercel.sh/v1/models", {
+        headers,
+        signal: AbortSignal.timeout(15000)
+    });
+    if (!response.ok) {
+        throw new Error(`models endpoint returned ${response.status} ${response.statusText}`);
+    }
+    const payload = await response.json();
+    return payload.data ?? [];
+}
+async function fetchModelsViaSdk() {
+    const result = await gateway.getAvailableModels();
+    return result.models.map((m) => ({
+        id: m.id,
+        name: m.name,
+        // SDK list exposes modelType but no capability tags
+        type: m.modelType
+    }));
+}
+export async function listGatewayModels(providerPrefix) {
+    let models;
+    try {
+        models = await fetchModelsRaw();
+    }
+    catch {
+        // Raw endpoint can fail (network/TLS); fall back to the SDK transport that
+        // already works for generation. This list lacks capability tags.
+        models = await fetchModelsViaSdk();
+    }
+    return providerPrefix ? models.filter((model) => model.id.startsWith(`${providerPrefix}/`)) : models;
+}
+/**
+ * Only text models that can use tools — the rest (image, video, embedding,
+ * reranking, or chat models without tool-use) cannot drive the research agent.
+ * When capability tags are unavailable (SDK fallback), accept any language model.
+ */
+export function isToolUseModel(model) {
+    if (model.type !== "language")
+        return false;
+    return model.tags === undefined ? true : model.tags.includes("tool-use");
+}
+export async function listToolUseModels(providerPrefix) {
+    return (await listGatewayModels(providerPrefix)).filter(isToolUseModel);
+}
+export const DEFAULT_MODEL = "deepseek/deepseek-v4-flash";
+export async function chooseConfiguredModel(config) {
+    requireLlmKeys(config);
+    return config.model || defaultModelFor(config.llmProvider);
+}
+export async function generateWithGateway(config, prompt, system) {
+    const result = await generateText({
+        model: getLanguageModel(config),
+        system,
+        prompt
+    });
+    return result.text;
+}

package/dist/providers/llm/huggingface.js

@@ -0,0 +1,33 @@
+async function fetchModelsRaw() {
+    const headers = {};
+    if (process.env.HF_API_KEY) {
+        headers.Authorization = `Bearer ${process.env.HF_API_KEY}`;
+    }
+    const response = await fetch("https://router.huggingface.co/v1/models", {
+        headers,
+        signal: AbortSignal.timeout(15000)
+    });
+    if (!response.ok) {
+        throw new Error(`HuggingFace models endpoint returned ${response.status} ${response.statusText}`);
+    }
+    const payload = await response.json();
+    return payload.data ?? [];
+}
+export async function listHuggingFaceModels() {
+    const allModels = await fetchModelsRaw();
+    return allModels.filter(isToolUseModel);
+}
+/**
+ * Only text models that can use tools — the rest (image, video, embedding,
+ * reranking, or chat models without tool-use) cannot drive the research agent.
+ */
+export function isToolUseModel(model) {
+    // Must support text input
+    if (!model.architecture.input_modalities.includes("text"))
+        return false;
+    // Must support text output
+    if (!model.architecture.output_modalities.includes("text"))
+        return false;
+    // At least one provider must support tools
+    return model.providers.some((p) => p.supports_tools === true);
+}

package/dist/providers/llm/models.js

@@ -0,0 +1,97 @@
+import { listToolUseModels } from "./gateway.js";
+import { listHuggingFaceModels } from "./huggingface.js";
+/** Curated fallbacks so the /model picker keeps working when the live list call fails. */
+const STATIC_MODELS = {
+    xai: [
+        { id: "grok-build-0.1", name: "Grok Build 0.1" },
+        { id: "grok-4", name: "Grok 4" },
+        { id: "grok-4-fast", name: "Grok 4 Fast" },
+        { id: "grok-4-fast-non-reasoning", name: "Grok 4 Fast (Non-Reasoning)" },
+        { id: "grok-3", name: "Grok 3" },
+        { id: "grok-3-mini", name: "Grok 3 Mini" }
+    ],
+    "workers-ai": [
+        { id: "@cf/moonshotai/kimi-k2.6", name: "Kimi K2.6" },
+        { id: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", name: "Llama 3.3 70B Instruct (fp8 fast)" },
+        { id: "@cf/meta/llama-4-scout-17b-16e-instruct", name: "Llama 4 Scout 17B Instruct" },
+        { id: "@cf/qwen/qwen2.5-coder-32b-instruct", name: "Qwen 2.5 Coder 32B Instruct" },
+        { id: "@cf/mistralai/mistral-small-3.1-24b-instruct", name: "Mistral Small 3.1 24B Instruct" },
+        { id: "@cf/openai/gpt-oss-120b", name: "GPT-OSS 120B" }
+    ],
+    huggingface: [
+        { id: "meta-llama/Llama-3.3-70B-Instruct", name: "Llama 3.3 70B Instruct" },
+        { id: "meta-llama/Llama-3.1-70B-Instruct", name: "Llama 3.1 70B Instruct" },
+        { id: "Qwen/Qwen2.5-72B-Instruct", name: "Qwen 2.5 72B Instruct" },
+        { id: "mistralai/Mistral-7B-Instruct-v0.3", name: "Mistral 7B Instruct v0.3" },
+        { id: "deepseek-ai/DeepSeek-V3", name: "DeepSeek V3" }
+    ]
+};
+async function listXaiModels() {
+    const key = process.env.XAI_API_KEY;
+    if (!key)
+        return STATIC_MODELS.xai;
+    try {
+        // OpenAI-compatible models endpoint
+        const response = await fetch("https://api.x.ai/v1/models", {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(15000)
+        });
+        if (!response.ok)
+            throw new Error(`xAI models endpoint returned ${response.status}`);
+        const payload = await response.json();
+        const models = (payload.data ?? []).map((m) => ({ id: m.id }));
+        return models.length > 0 ? models : STATIC_MODELS.xai;
+    }
+    catch {
+        return STATIC_MODELS.xai;
+    }
+}
+async function listWorkersAiModels() {
+    const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+    const token = process.env.CLOUDFLARE_API_TOKEN;
+    if (!accountId || !token)
+        return STATIC_MODELS["workers-ai"];
+    try {
+        const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/models/search?task=Text%20Generation&per_page=100`;
+        const response = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(15000)
+        });
+        if (!response.ok)
+            throw new Error(`Cloudflare models endpoint returned ${response.status}`);
+        const payload = await response.json();
+        const models = (payload.result ?? [])
+            // prefer models that declare function calling; keep all if the flag is absent everywhere
+            .map((m) => ({
+            id: m.name,
+            functionCalling: (m.properties ?? []).some((p) => p.property_id === "function_calling" && p.value === "true")
+        }));
+        const toolCapable = models.filter((m) => m.functionCalling);
+        const chosen = toolCapable.length > 0 ? toolCapable : models;
+        return chosen.length > 0 ? chosen.map(({ id }) => ({ id })) : STATIC_MODELS["workers-ai"];
+    }
+    catch {
+        return STATIC_MODELS["workers-ai"];
+    }
+}
+async function listHuggingFaceModelsWrapper() {
+    const key = process.env.HF_API_KEY;
+    if (!key)
+        return STATIC_MODELS.huggingface;
+    try {
+        const models = await listHuggingFaceModels();
+        return models.length > 0 ? models.map((m) => ({ id: m.id })) : STATIC_MODELS.huggingface;
+    }
+    catch {
+        return STATIC_MODELS.huggingface;
+    }
+}
+/** Model list for the active LLM provider (live where possible, static fallback otherwise). */
+export async function listModels(config) {
+    switch (config.llmProvider) {
+        case "xai": return listXaiModels();
+        case "workers-ai": return listWorkersAiModels();
+        case "huggingface": return listHuggingFaceModelsWrapper();
+        default: return (await listToolUseModels()).map((m) => ({ id: m.id, name: m.name }));
+    }
+}

package/dist/providers/llm/readiness.js

@@ -0,0 +1,50 @@
+import process from "node:process";
+export const PROVIDER_ENV = {
+    parallel: "PARALLEL_API_KEY",
+    exa: "EXA_API_KEY",
+    firecrawl: "FIRECRAWL_API_KEY"
+};
+export const AI_GATEWAY_ENV = "AI_GATEWAY_API_KEY";
+export function hasEnv(name) {
+    const value = process.env[name];
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function requireAiGatewayKey() {
+    if (!hasEnv(AI_GATEWAY_ENV)) {
+        throw new Error(`${AI_GATEWAY_ENV} is required for AI-powered research. Set it in your environment before running plans, searches, or reports.`);
+    }
+}
+export function providerEnvVar(provider) {
+    return PROVIDER_ENV[provider];
+}
+export function requireSearchProvider(provider) {
+    const name = PROVIDER_ENV[provider];
+    if (!hasEnv(name)) {
+        throw new Error(`${name} is required for the "${provider}" search/scrape provider. Set it in your environment or switch search.provider in config.`);
+    }
+}
+const LLM_ENV_CHECKS = [
+    { name: AI_GATEWAY_ENV, provider: "gateway", purpose: "Vercel AI Gateway LLM access" },
+    { name: "XAI_API_KEY", provider: "xai", purpose: "xAI (Grok) LLM access" },
+    { name: "CLOUDFLARE_ACCOUNT_ID", provider: "workers-ai", purpose: "Cloudflare Workers AI account" },
+    { name: "CLOUDFLARE_API_TOKEN", provider: "workers-ai", purpose: "Cloudflare Workers AI LLM access" },
+    { name: "HF_API_KEY", provider: "huggingface", purpose: "HuggingFace Inference API access" }
+];
+export function detectEnv(provider, llmProvider = "gateway") {
+    const checks = LLM_ENV_CHECKS.map((c) => ({
+        name: c.name,
+        present: hasEnv(c.name),
+        purpose: c.purpose,
+        required: c.provider === llmProvider
+    }));
+    for (const key of Object.keys(PROVIDER_ENV)) {
+        const name = PROVIDER_ENV[key];
+        checks.push({
+            name,
+            present: hasEnv(name),
+            purpose: `${key} web search + scrape`,
+            required: key === provider
+        });
+    }
+    return checks;
+}

package/dist/providers/llm/registry.js

@@ -0,0 +1,56 @@
+import { gateway } from "ai";
+import { createXai } from "@ai-sdk/xai";
+import { createWorkersAI } from "workers-ai-provider";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { hasEnv } from "./readiness.js";
+export const LLM_PROVIDERS = ["gateway", "xai", "workers-ai", "huggingface"];
+/** Human-readable names for the provider picker and status messages. */
+export const LLM_PROVIDER_LABELS = {
+    gateway: "Vercel AI Gateway",
+    xai: "xAI",
+    "workers-ai": "Cloudflare Workers AI",
+    huggingface: "HuggingFace"
+};
+/** Env vars each LLM provider needs before it can generate. */
+export const LLM_PROVIDER_ENV = {
+    gateway: ["AI_GATEWAY_API_KEY"],
+    xai: ["XAI_API_KEY"],
+    "workers-ai": ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"],
+    huggingface: ["HF_API_KEY"]
+};
+export function defaultModelFor(provider) {
+    switch (provider) {
+        case "xai": return "grok-build-0.1";
+        case "workers-ai": return "@cf/moonshotai/kimi-k2.6";
+        case "huggingface": return "meta-llama/Llama-3.3-70B-Instruct";
+        default: return "deepseek/deepseek-v4-flash";
+    }
+}
+/** Throw a setup-oriented error when the active LLM provider's env keys are missing. */
+export function requireLlmKeys(config) {
+    const missing = LLM_PROVIDER_ENV[config.llmProvider].filter((name) => !hasEnv(name));
+    if (missing.length > 0) {
+        throw new Error(`${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} required for the "${config.llmProvider}" LLM provider. Set ${missing.length === 1 ? "it" : "them"} with /key or in your environment.`);
+    }
+}
+/** Build the AI SDK language model for the configured provider + model id. */
+export function getLanguageModel(config) {
+    requireLlmKeys(config);
+    switch (config.llmProvider) {
+        case "xai":
+            return createXai({ apiKey: process.env.XAI_API_KEY })(config.model);
+        case "workers-ai":
+            return createWorkersAI({
+                accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+                apiKey: process.env.CLOUDFLARE_API_TOKEN
+            })(config.model);
+        case "huggingface":
+            return createOpenAICompatible({
+                name: "huggingface",
+                baseURL: "https://router.huggingface.co/v1",
+                apiKey: process.env.HF_API_KEY
+            })(config.model);
+        default:
+            return gateway(config.model);
+    }
+}

package/dist/storage/jsonl.js

@@ -0,0 +1,29 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export async function appendJsonl(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value)}\n`, { flag: "a" });
+}
+export async function readJsonl(path) {
+    try {
+        const text = await readFile(path, "utf8");
+        const results = [];
+        for (const line of text.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                results.push(JSON.parse(line));
+            }
+            catch {
+                // skip malformed/truncated lines (e.g. agent wrote unescaped newlines in a value)
+            }
+        }
+        return results;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}

package/dist/storage/jsonl.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { appendJsonl, readJsonl } from "./jsonl.js";
+describe("readJsonl / appendJsonl", () => {
+    let dir;
+    let file;
+    beforeEach(async () => {
+        dir = await mkdtemp(join(tmpdir(), "scira-test-"));
+        file = join(dir, "test.jsonl");
+    });
+    afterEach(async () => {
+        await rm(dir, { recursive: true, force: true });
+    });
+    it("returns [] for a missing file", async () => {
+        expect(await readJsonl(join(dir, "missing.jsonl"))).toEqual([]);
+    });
+    it("round-trips a single object", async () => {
+        await appendJsonl(file, { id: "c1", text: "hello" });
+        expect(await readJsonl(file)).toEqual([{ id: "c1", text: "hello" }]);
+    });
+    it("appends multiple objects sequentially", async () => {
+        await appendJsonl(file, { n: 1 });
+        await appendJsonl(file, { n: 2 });
+        await appendJsonl(file, { n: 3 });
+        expect(await readJsonl(file)).toEqual([{ n: 1 }, { n: 2 }, { n: 3 }]);
+    });
+    it("skips malformed lines without throwing", async () => {
+        await writeFile(file, '{"ok":true}\nNOT_JSON\n{"ok":false}\n');
+        expect(await readJsonl(file)).toEqual([{ ok: true }, { ok: false }]);
+    });
+    it("creates parent directories that do not exist", async () => {
+        const nested = join(dir, "a", "b", "c.jsonl");
+        await appendJsonl(nested, { x: 1 });
+        expect(await readJsonl(nested)).toEqual([{ x: 1 }]);
+    });
+});

package/dist/storage/run-store.js

@@ -0,0 +1,134 @@
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createRunId } from "../utils/ids.js";
+import { appendJsonl, readJsonl } from "./jsonl.js";
+export function getRunPaths(runPath) {
+    return {
+        root: runPath,
+        goal: join(runPath, "goal.md"),
+        plan: join(runPath, "plan.md"),
+        research: join(runPath, "RESEARCH.md"),
+        scope: join(runPath, "scope.json"),
+        progress: join(runPath, "progress.md"),
+        sources: join(runPath, "sources.jsonl"),
+        claims: join(runPath, "claims.jsonl"),
+        notes: join(runPath, "notes.md"),
+        report: join(runPath, "report.md"),
+        log: join(runPath, "run.log.jsonl"),
+        handoff: join(runPath, "handoff.md"),
+        artifacts: join(runPath, "artifacts"),
+        snapshots: join(runPath, "snapshots")
+    };
+}
+export async function createRun(goal, config, projectRoot = process.cwd()) {
+    const runId = createRunId(goal);
+    const runPath = resolve(projectRoot, config.runDirectory, runId);
+    const paths = getRunPaths(runPath);
+    await mkdir(paths.artifacts, { recursive: true });
+    await mkdir(paths.snapshots, { recursive: true });
+    await writeFile(paths.goal, `# Goal\n\n${goal}\n`);
+    await writeFile(paths.plan, "# Research Plan\n\nPending plan generation.\n");
+    await writeFile(paths.research, researchInstructions());
+    await writeFile(paths.scope, `${JSON.stringify({ goal, maxSources: config.maxSources, citationPolicy: config.citationPolicy }, null, 2)}\n`);
+    await writeFile(paths.progress, progressText("created", "Generate and approve research plan."));
+    await writeFile(paths.sources, "");
+    await writeFile(paths.claims, "");
+    await writeFile(paths.notes, "# Notes\n\n");
+    await writeFile(paths.report, "# Report\n\nDraft not generated yet.\n");
+    await writeFile(paths.handoff, handoffText(goal, "created"));
+    await logEvent(paths.root, "run.created", { goal });
+    return summarizeRun(paths.root);
+}
+export async function summarizeRun(runPath) {
+    const paths = getRunPaths(runPath);
+    const goal = (await readFile(paths.goal, "utf8").catch(() => "")).replace(/^# Goal\s*/u, "").trim();
+    const title = (await readFile(join(runPath, "title.md"), "utf8").catch(() => "")).trim() || undefined;
+    const sources = await readJsonl(paths.sources);
+    const claims = await readJsonl(paths.claims);
+    const report = await readFile(paths.report, "utf8").catch(() => "");
+    // last activity = newest mtime among the files that change as a run progresses
+    const mtimes = await Promise.all([join(runPath, "convo.json"), paths.report, runPath].map((p) => stat(p).then((s) => s.mtimeMs).catch(() => 0)));
+    const updatedAt = Math.max(0, ...mtimes);
+    return {
+        id: runPath.split(/[\\/]/u).at(-1) ?? runPath,
+        path: runPath,
+        goal,
+        title,
+        sourceCount: sources.length,
+        claimCount: claims.length,
+        weakCount: claims.filter((claim) => claim.status === "weak").length,
+        reportDirty: report.length < 200 || report.includes("Draft not generated yet"),
+        updatedAt,
+        isFull: sources.length > 0 || claims.length > 0
+    };
+}
+export async function setRunTitle(runPath, title) {
+    await writeFile(join(runPath, "title.md"), title.trim());
+}
+export async function deleteRun(runPath) {
+    await rm(runPath, { recursive: true, force: true });
+}
+/** Build a human-readable verification report from the run's claim ledger (scope §16.2). */
+export async function verificationReport(runPath) {
+    const claims = await readJsonl(getRunPaths(runPath).claims);
+    if (claims.length === 0) {
+        return "No claims recorded yet. Run the research agent first.";
+    }
+    const count = (status) => claims.filter((c) => c.status === status).length;
+    const lines = [
+        "Verification Report",
+        "",
+        `Claims: ${claims.length}`,
+        `Verified: ${count("verified")}`,
+        `Weak: ${count("weak")}`,
+        `Contradicted: ${count("contradicted")}`,
+        `Needs review: ${count("needs_review")}`,
+        `Draft: ${count("draft")}`
+    ];
+    const flagged = claims.filter((c) => c.status === "weak" || c.status === "contradicted" || c.status === "needs_review");
+    for (const claim of flagged) {
+        lines.push("", `${claim.id} (${claim.status}): "${claim.text}"`, `Reason: ${claim.reason || "n/a"}`);
+    }
+    return lines.join("\n");
+}
+export async function listRuns(config, projectRoot = process.cwd()) {
+    const runsRoot = resolve(projectRoot, config.runDirectory);
+    try {
+        const entries = await readdir(runsRoot);
+        const dirs = await Promise.all(entries.map(async (entry) => {
+            const path = join(runsRoot, entry);
+            return (await stat(path)).isDirectory() ? path : undefined;
+        }));
+        const settled = await Promise.allSettled(dirs.filter((path) => Boolean(path)).map(summarizeRun));
+        return settled
+            .filter((r) => r.status === "fulfilled")
+            .map((r) => r.value)
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}
+export async function findRun(runId, config, projectRoot = process.cwd()) {
+    const runs = await listRuns(config, projectRoot);
+    const run = runs.find((candidate) => candidate.id === runId || candidate.id.includes(runId));
+    if (!run) {
+        throw new Error(`Run not found: ${runId}`);
+    }
+    return run.path;
+}
+export async function logEvent(runPath, type, data = {}) {
+    await appendJsonl(getRunPaths(runPath).log, { type, data, createdAt: new Date().toISOString() });
+}
+export function progressText(status, next) {
+    return `# Progress\n\nStatus: ${status}\n\nNext: ${next}\n`;
+}
+export function handoffText(goal, status) {
+    return `# Handoff\n\nGoal: ${goal}\n\nStatus: ${status}\n\nNext agent should inspect \`progress.md\`, \`sources.jsonl\`, \`claims.jsonl\`, and \`report.md\`.\n`;
+}
+function researchInstructions() {
+    return `# Research Instructions\n\n- Prefer primary sources.\n- Never make uncited claims in final reports.\n- Mark vendor claims as vendor claims.\n- Check dates for pricing, market, company, and product claims.\n- Search for contradictions before finalizing.\n- Do not overstate weak evidence.\n- Put uncertain claims in the risks or open questions section.\n`;
+}

package/dist/storage/run-store.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createRun, summarizeRun, setRunTitle, getRunPaths } from "./run-store.js";
+import { SciraConfigSchema } from "../types/index.js";
+import { appendJsonl } from "./jsonl.js";
+const BASE_CONFIG = SciraConfigSchema.parse({});
+describe("createRun / summarizeRun", () => {
+    let tmpRoot;
+    beforeEach(async () => {
+        tmpRoot = await mkdtemp(join(tmpdir(), "scira-runs-"));
+    });
+    afterEach(async () => {
+        await rm(tmpRoot, { recursive: true, force: true });
+    });
+    it("creates all expected files and subdirectories", async () => {
+        const config = { ...BASE_CONFIG, runDirectory: tmpRoot };
+        const state = await createRun("What is the speed of light?", config, "");
+        const paths = getRunPaths(state.path);
+        const { readFile, stat } = await import("node:fs/promises");
+        await expect(readFile(paths.goal, "utf8")).resolves.toContain("speed of light");
+        await expect(stat(paths.artifacts)).resolves.toBeDefined();
+        await expect(stat(paths.snapshots)).resolves.toBeDefined();
+    });
+    it("summarizeRun reflects zero sources and claims on a fresh run", async () => {
+        const config = { ...BASE_CONFIG, runDirectory: tmpRoot };
+        const state = await createRun("Test question", config, "");
+        expect(state.sourceCount).toBe(0);
+        expect(state.claimCount).toBe(0);
+        expect(state.weakCount).toBe(0);
+        expect(state.isFull).toBe(false);
+        expect(state.reportDirty).toBe(true);
+        expect(state.goal).toContain("Test question");
+    });
+    it("setRunTitle persists the title and summarizeRun reads it back", async () => {
+        const config = { ...BASE_CONFIG, runDirectory: tmpRoot };
+        const state = await createRun("Title test", config, "");
+        await setRunTitle(state.path, "My Custom Title");
+        const updated = await summarizeRun(state.path);
+        expect(updated.title).toBe("My Custom Title");
+    });
+    it("isFull becomes true once a source is appended", async () => {
+        const config = { ...BASE_CONFIG, runDirectory: tmpRoot };
+        const state = await createRun("Full test", config, "");
+        const paths = getRunPaths(state.path);
+        await appendJsonl(paths.sources, {
+            id: "s1", title: "Test", url: "https://test.com",
+            kind: "primary", summary: "", createdAt: new Date().toISOString()
+        });
+        const updated = await summarizeRun(state.path);
+        expect(updated.sourceCount).toBe(1);
+        expect(updated.isFull).toBe(true);
+    });
+    it("weakCount reflects weak claims", async () => {
+        const config = { ...BASE_CONFIG, runDirectory: tmpRoot };
+        const state = await createRun("Weak test", config, "");
+        const paths = getRunPaths(state.path);
+        await appendJsonl(paths.claims, { id: "c1", text: "x", confidence: "low", status: "weak", sourceIds: [], reason: "", createdAt: new Date().toISOString() });
+        await appendJsonl(paths.claims, { id: "c2", text: "y", confidence: "high", status: "verified", sourceIds: [], reason: "", createdAt: new Date().toISOString() });
+        const updated = await summarizeRun(state.path);
+        expect(updated.claimCount).toBe(2);
+        expect(updated.weakCount).toBe(1);
+    });
+});

package/dist/tools/chrome-devtools-mcp.js

@@ -0,0 +1,61 @@
+import { createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+const NOOP_BRIDGE = {
+    tools: {},
+    close: async () => { },
+    toolNames: []
+};
+/**
+ * Spin up the Chrome DevTools MCP server over stdio and return its tools as
+ * an AI SDK ToolSet, prefixed to avoid collisions with Scira's built-in tools.
+ *
+ * If the bridge is disabled in config, or if the MCP server fails to start,
+ * this returns a no-op bridge so the agent can still run with built-in tools.
+ */
+export async function createChromeDevtoolsMcpBridge(config) {
+    const cfg = config.mcp.chromeDevtools;
+    if (!cfg.enabled)
+        return NOOP_BRIDGE;
+    let client;
+    try {
+        client = await createMCPClient({
+            transport: new Experimental_StdioMCPTransport({
+                command: cfg.command,
+                args: cfg.args,
+                stderr: "pipe"
+            }),
+            clientName: "scira-cli"
+        });
+        const raw = await client.tools();
+        const prefix = cfg.toolPrefix ?? "";
+        const prefixed = {};
+        const toolNames = [];
+        for (const [name, tool] of Object.entries(raw)) {
+            const finalName = prefix ? `${prefix}${name}` : name;
+            prefixed[finalName] = tool;
+            toolNames.push(finalName);
+        }
+        const owned = client;
+        return {
+            tools: prefixed,
+            close: async () => {
+                try {
+                    await owned.close();
+                }
+                catch { /* ignore */ }
+            },
+            toolNames
+        };
+    }
+    catch (error) {
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch { /* ignore */ }
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`\n[scira] Chrome DevTools MCP unavailable, continuing without it: ${message}\n`);
+        return NOOP_BRIDGE;
+    }
+}