@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/pages.js

@@ -0,0 +1,184 @@
+import { documentationCollections, collectionForPath } from './documentation-collections.js';
+import { resolvePageRoute } from './page-routes.js';
+import { readFile } from 'node:fs/promises';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import { DoxloopError } from './errors.js';
+import { EVIDENCE_MAP_FILE, readEvidenceMap } from './evidence.js';
+import { assertInside, pathExists, resolveContainedDirectory } from './fs.js';
+import { listPages as listHistoryPages } from './history.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { loadPages, loadProject, loadSiteConfig, pageExtensions, pageId, readPage, relativePath, siteConfigPath, } from './project.js';
+import { readDoxbrixNavigation } from './validation.js';
+export async function listPages(root) {
+    const project = await loadProject(root);
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Documentation content directory', {
+        allowRoot: project.generator === 'doxbrix',
+    });
+    const collections = await documentationCollections(root, project);
+    const files = await loadPages(root, project);
+    const adapter = project.generator === 'doxbrix' ? undefined : await loadGeneratorAdapter(root, project);
+    const navigation = project.generator === 'doxbrix'
+        ? readDoxbrixNavigation((await loadSiteConfig(root, project)).spaces)
+        : [];
+    const navigationById = new Map(navigation.map((entry, index) => [entry.path, { ...entry, index }]));
+    const evidence = await readEvidenceMap(root);
+    const history = new Map((await listHistoryPages(root)).map((page) => [portable(page.path), page]));
+    const summaries = await Promise.all(files.map(async (absolute) => {
+        const path = relativePath(root, absolute);
+        const id = pageId(contentRoot, absolute);
+        const page = adapter?.readPage ? await adapter.readPage(absolute) : await readPage(absolute);
+        const nav = navigationById.get(id);
+        return {
+            path,
+            version: collectionForPath(collections, path)?.version ?? 'current',
+            locale: collectionForPath(collections, path)?.locale ?? 'default',
+            title: page.title || titleFromPath(path),
+            ...(page.description ? { description: page.description } : {}),
+            ...(nav?.section ? { section: nav.section } : {}),
+            route: await resolvePageRoute(root, project, path),
+            wordCount: countWords(page.body),
+            ...(history.get(path)?.updatedAt ? { updatedAt: history.get(path).updatedAt } : {}),
+            evidence: evidenceState(evidence?.pages[path], project.sync.maxVerificationAgeDays),
+            inNavigation: Boolean(nav) || project.generator !== 'doxbrix',
+            order: nav?.index ?? Number.MAX_SAFE_INTEGER,
+        };
+    }));
+    return summaries
+        .sort((left, right) => left.order - right.order || left.title.localeCompare(right.title) || left.path.localeCompare(right.path))
+        .map(({ order: _order, ...summary }) => summary);
+}
+/** Map a project-relative page file to the conventional local-preview route. */
+export function pageRoute(project, path) {
+    // External adapters do not currently expose route mapping, so all generators
+    // use the same content-relative convention until that API grows one.
+    const content = portable(project.contentDir).replace(/^\/+|\/+$/g, '');
+    let route = portable(path).replace(/^\/+/, '');
+    if (content && (route === content || route.startsWith(`${content}/`))) {
+        route = route.slice(content.length).replace(/^\/+/, '');
+    }
+    route = route.replace(/\.[^./]+$/, '');
+    route = route.replace(/(^|\/)index$/, '');
+    return `/${route}`.replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+}
+export async function resolveEditScope(root, project, paths, allowRelated) {
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Documentation content directory', {
+        allowRoot: project.generator === 'doxbrix',
+    });
+    const pages = new Set((await loadPages(root, project)).map((path) => relativePath(root, path)));
+    const extensions = await pageExtensions(root, project);
+    const collections = await documentationCollections(root, project);
+    const selectedPaths = new Set();
+    for (const raw of paths) {
+        const path = portable(raw.trim()).replace(/^\.\//, '');
+        const absolute = resolve(root, path);
+        let insideContent = false;
+        try {
+            const collection = collectionForPath(collections, path);
+            const allowedRoot = collection ? resolve(root, collection.directory) : contentRoot;
+            assertInside(allowedRoot, absolute);
+            insideContent = Boolean(collection) && (absolute === allowedRoot || relative(allowedRoot, absolute).split(sep)[0] !== '..');
+        }
+        catch {
+            insideContent = false;
+        }
+        if (!path ||
+            path.split('/').some((part) => ['..', '.doxloop', 'node_modules'].includes(part)) ||
+            !insideContent ||
+            !extensions.has(extname(path).toLowerCase()) ||
+            !pages.has(path)) {
+            throw new DoxloopError(`"${raw}" is not an existing documentation page inside ${project.contentDir || 'the project root'}.`, 2);
+        }
+        selectedPaths.add(path);
+    }
+    if (selectedPaths.size === 0)
+        throw new DoxloopError('Select at least one documentation page to edit.', 2);
+    const supportingPaths = new Set([EVIDENCE_MAP_FILE]);
+    const supportingPrefixes = new Set();
+    if (allowRelated) {
+        if (project.generator === 'doxbrix') {
+            supportingPaths.add(relativePath(root, await siteConfigPath(root, project)));
+        }
+        else {
+            const adapter = await loadGeneratorAdapter(root, project);
+            for (const path of adapter.planning?.navigationFiles ?? [])
+                supportingPaths.add(portable(path));
+        }
+        for (const path of selectedPaths) {
+            const raw = await readFile(join(root, path), 'utf8');
+            for (const reference of assetReferences(raw)) {
+                const resolved = await resolveReferencedAsset(root, contentRoot, path, reference, project);
+                if (resolved)
+                    supportingPaths.add(resolved);
+            }
+            const slug = path.split('/').at(-1).replace(/\.[^.]+$/, '');
+            for (const base of ['assets', 'public/assets', 'static/assets', portable(join(project.contentDir, 'assets'))]) {
+                const normalized = base.replace(/^\/+|\/+$/g, '');
+                if (normalized)
+                    supportingPrefixes.add(`${normalized}/${slug}`);
+            }
+        }
+    }
+    return {
+        selectedPaths,
+        supportingPaths,
+        supportingPrefixes,
+        pageExtensions: extensions,
+        wholeProposal: false,
+        hunkRanges: new Map(),
+    };
+}
+function evidenceState(entry, maxAgeDays) {
+    if (!entry)
+        return 'none';
+    if (entry.confidence === 'needs-human' || entry.confidence === 'inferred' || Object.values(entry.claimVerification ?? {}).some((state) => state !== 'verified')) {
+        return 'needs-review';
+    }
+    const verificationDates = Object.values(entry.verifiedOn ?? {}).map(Date.parse).filter(Number.isFinite);
+    const hasVerification = Object.keys(entry.claimVerification ?? {}).length > 0 || Object.keys(entry.verifiedAt ?? {}).length > 0;
+    if (!hasVerification)
+        return 'needs-review';
+    if (maxAgeDays && verificationDates.length > 0 && verificationDates.every((date) => Date.now() - date > maxAgeDays * 86_400_000)) {
+        return 'needs-review';
+    }
+    return 'verified';
+}
+function countWords(value) {
+    return value.replace(/```[\s\S]*?```/g, ' ').replace(/<[^>]+>/g, ' ').match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu)?.length ?? 0;
+}
+function titleFromPath(path) {
+    return path.split('/').at(-1).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function assetReferences(raw) {
+    const references = new Set();
+    for (const pattern of [/!\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g, /\b(?:src|href)=["']([^"']+)["']/g]) {
+        for (const match of raw.matchAll(pattern)) {
+            const reference = match[1]?.trim();
+            if (reference && !/^(?:https?:|data:|#)/i.test(reference))
+                references.add(reference);
+        }
+    }
+    return [...references];
+}
+async function resolveReferencedAsset(root, contentRoot, pagePath, reference, project) {
+    const adapter = project.generator === 'doxbrix' ? undefined : await loadGeneratorAdapter(root, project);
+    const candidates = [
+        adapter?.resolveLocalAsset?.({ root, contentRoot, pagePath: join(root, pagePath), reference }),
+        reference.startsWith('/') ? resolve(root, reference.slice(1)) : resolve(join(root, pagePath, '..'), reference),
+        reference.startsWith('/') ? resolve(contentRoot, reference.slice(1)) : undefined,
+    ].filter((value) => Boolean(value));
+    for (const candidate of candidates) {
+        try {
+            const safe = assertInside(root, candidate);
+            if (await pathExists(safe))
+                return relativePath(root, safe);
+        }
+        catch {
+            // External URLs and assets outside the documentation project are not editable support files.
+        }
+    }
+    return undefined;
+}
+function portable(path) {
+    return sep === '/' ? path : path.split(sep).join('/');
+}
+//# sourceMappingURL=pages.js.map

package/dist/plan-generator.d.ts

@@ -0,0 +1,3 @@
+import type { DocumentationPlanTarget, DoxloopProject } from './types.js';
+export declare function documentationPlanTarget(root: string, project: DoxloopProject): Promise<DocumentationPlanTarget>;
+//# sourceMappingURL=plan-generator.d.ts.map

package/dist/plan-generator.js

@@ -0,0 +1,21 @@
+import { loadGeneratorAdapter } from './generators.js';
+export async function documentationPlanTarget(root, project) {
+    if (project.generator === 'doxbrix') {
+        return {
+            generator: 'doxbrix',
+            contentDir: project.contentDir,
+            contentFormat: 'markdown',
+            pageExtensions: ['.md', '.mdx'],
+            navigationFiles: [project.contentDir ? `${project.contentDir}/docs.json` : 'docs.json'],
+        };
+    }
+    const adapter = await loadGeneratorAdapter(root, project);
+    return {
+        generator: project.generator,
+        contentDir: project.contentDir,
+        contentFormat: adapter.project.contentFormat ?? 'markdown',
+        pageExtensions: adapter.project.pageExtensions,
+        navigationFiles: adapter.planning?.navigationFiles ?? [],
+    };
+}
+//# sourceMappingURL=plan-generator.js.map

package/dist/plan-navigation.d.ts

@@ -0,0 +1,11 @@
+import type { DocumentationPlanNavigation } from './types.js';
+/**
+ * Every navigation section names the space its group lives in, so a plan
+ * with several spaces is built with several spaces. A section the planner
+ * gave a known space keeps it (matched case-insensitively); otherwise it goes
+ * to the space whose name shares a word with the section title ("APIs" →
+ * "API & integrations"). Any other section keeps no space, so navigation
+ * repair places it by its pages' paths or in the primary space.
+ */
+export declare function assignSectionSpaces<T extends DocumentationPlanNavigation['sections'][number]>(top: readonly string[], sections: readonly T[]): T[];
+//# sourceMappingURL=plan-navigation.d.ts.map

package/dist/plan-navigation.js

@@ -0,0 +1,30 @@
+const SPACE_WORD_STOP = new Set(['and', 'the', 'a', 'an', 'of', 'for', 'to', 'with', 'your', 'in', 'on', 'docs', 'documentation', 'guide', 'guides']);
+function spaceWords(value) {
+    return new Set(value.toLowerCase().split(/[^a-z0-9]+/).filter((word) => word && !SPACE_WORD_STOP.has(word)).map((word) => word.replace(/(?:ies)$/, 'y').replace(/s$/, '')));
+}
+/**
+ * Every navigation section names the space its group lives in, so a plan
+ * with several spaces is built with several spaces. A section the planner
+ * gave a known space keeps it (matched case-insensitively); otherwise it goes
+ * to the space whose name shares a word with the section title ("APIs" →
+ * "API & integrations"). Any other section keeps no space, so navigation
+ * repair places it by its pages' paths or in the primary space.
+ */
+export function assignSectionSpaces(top, sections) {
+    if (top.length === 0)
+        return [...sections];
+    const byKey = new Map(top.map((name) => [name.trim().toLowerCase(), name]));
+    const secondary = top.slice(1).map((name) => ({ name, words: spaceWords(name) }));
+    return sections.map((section) => {
+        const named = section.space ? byKey.get(section.space.trim().toLowerCase()) : undefined;
+        if (named)
+            return { ...section, space: named };
+        const titleWords = spaceWords(section.title);
+        const match = secondary.find((candidate) => [...candidate.words].some((word) => titleWords.has(word)));
+        if (match)
+            return { ...section, space: match.name };
+        const { space: _unknown, ...rest } = section;
+        return rest;
+    });
+}
+//# sourceMappingURL=plan-navigation.js.map

package/dist/planning-captures.d.ts

@@ -0,0 +1,20 @@
+import type { DocumentationPlan } from './types.js';
+export declare function preparePlanningCaptures(root: string, planId: string): Promise<string>;
+export interface PlanningCaptureReuse {
+    reused: number;
+    /** Capture IDs the plan references that no saved image could be found for. */
+    missing: string[];
+}
+/**
+ * Reuse only explicitly selected, reviewed images belonging to this plan's
+ * research.
+ *
+ * The browser tool saves an auto-named file into the capture directory but
+ * resolves a caller-supplied filename against its client workspace, so an
+ * agent that names its images (as the prompt asks) leaves them at the
+ * project root. Those are adopted from there and moved into the plan's
+ * capture directory, where the plan's evidence stays together.
+ */
+export declare function reusePlanningCaptures(root: string, workspace: string, plan: DocumentationPlan, generator: string): Promise<number>;
+export declare function adoptPlanningCaptures(root: string, workspace: string, plan: DocumentationPlan, generator: string): Promise<PlanningCaptureReuse>;
+//# sourceMappingURL=planning-captures.d.ts.map

package/dist/planning-captures.js

@@ -0,0 +1,143 @@
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { PNG } from 'pngjs';
+import { GUIDE_ASSET_ROOTS, SCREENSHOT_MANIFEST_FILE, dominantColorShare } from './screenshot-workflow.js';
+export async function preparePlanningCaptures(root, planId) {
+    if (!/^[\w-]+$/.test(planId))
+        throw new Error('Invalid capture plan ID');
+    const directory = join(root, '.doxloop', 'plans', planId, 'captures');
+    await mkdir(directory, { recursive: true });
+    return directory;
+}
+/**
+ * Reuse only explicitly selected, reviewed images belonging to this plan's
+ * research.
+ *
+ * The browser tool saves an auto-named file into the capture directory but
+ * resolves a caller-supplied filename against its client workspace, so an
+ * agent that names its images (as the prompt asks) leaves them at the
+ * project root. Those are adopted from there and moved into the plan's
+ * capture directory, where the plan's evidence stays together.
+ */
+export async function reusePlanningCaptures(root, workspace, plan, generator) {
+    return (await adoptPlanningCaptures(root, workspace, plan, generator)).reused;
+}
+export async function adoptPlanningCaptures(root, workspace, plan, generator) {
+    const directory = await preparePlanningCaptures(root, plan.id);
+    const missing = [];
+    let brief;
+    try {
+        brief = JSON.parse(await readFile(join(root, '.doxloop', 'plans', plan.id, 'research', 'application.json'), 'utf8'));
+    }
+    catch {
+        return { reused: 0, missing };
+    }
+    const captures = new Map();
+    const duplicate = new Set();
+    for (const screen of Array.isArray(brief.content?.screens) ? brief.content.screens : []) {
+        for (const capture of Array.isArray(screen?.captures) ? screen.captures : []) {
+            if (!capture || typeof capture.id !== 'string')
+                continue;
+            if (captures.has(capture.id))
+                duplicate.add(capture.id);
+            captures.set(capture.id, { ...capture, route: screen.route, labels: screen.visible });
+        }
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(workspace, SCREENSHOT_MANIFEST_FILE), 'utf8'));
+    }
+    catch {
+        return { reused: 0, missing };
+    }
+    let reused = 0;
+    const catalog = [];
+    for (const guide of Array.isArray(manifest.guides) ? manifest.guides : []) {
+        if (!Array.isArray(guide?.steps))
+            continue;
+        const page = plan.pages.find((page) => page.id === guide.page || page.path === guide.page);
+        for (const [index, step] of guide.steps.entries()) {
+            const sequenceIndex = typeof step.sequenceItem === 'number' ? step.sequenceItem - 1 : index;
+            const capture = captures.get(page?.visuals?.captureIds?.[sequenceIndex] ?? '');
+            if (!capture || duplicate.has(capture.id))
+                continue;
+            if (step.status === 'verified' && typeof step.file === 'string') {
+                try {
+                    await readFile(join(workspace, step.file));
+                    continue;
+                }
+                catch {
+                    step.status = 'planned';
+                }
+            }
+            if (!capture.file || !capture.alt || !capture.state || !['expectedStateConfirmed', 'privacyReviewed', 'legibilityReviewed', 'meaningful'].every((key) => capture.checks?.[key] === true))
+                continue;
+            try {
+                const source = await locateCapture(directory, root, capture.file);
+                if (!source) {
+                    missing.push(capture.id);
+                    continue;
+                }
+                const bytes = await readFile(source);
+                if (bytes.length > 20_000_000)
+                    continue;
+                const png = PNG.sync.read(bytes);
+                if (png.width < 320 || png.height < 180 || dominantColorShare(png) > 0.995)
+                    continue;
+                const assetRoot = join(plan.target?.contentDir ?? '', GUIDE_ASSET_ROOTS[generator] ?? GUIDE_ASSET_ROOTS.doxbrix);
+                const file = join(assetRoot, 'planning', `${plan.id}-${createHash('sha256').update(bytes).digest('hex').slice(0, 16)}.png`).replaceAll('\\', '/');
+                await mkdir(join(workspace, assetRoot, 'planning'), { recursive: true });
+                await copyFile(source, join(workspace, file));
+                Object.assign(step, { file, alt: capture.alt, status: 'verified', target: typeof step.action === 'string' && step.action ? step.action : capture.action, checks: capture.checks, observedState: capture.state, observedLabels: capture.labels });
+                catalog.push({ ...capture, file });
+                reused += 1;
+            }
+            catch { /* Missing or corrupt images remain planned for the capture stage. */ }
+        }
+    }
+    await writeFile(join(workspace, SCREENSHOT_MANIFEST_FILE), JSON.stringify(manifest, null, 2));
+    await mkdir(join(workspace, '.doxloop', 'cache'), { recursive: true });
+    if (catalog.length > 0)
+        await writeFile(join(workspace, '.doxloop', 'cache', 'planning-captures.json'), JSON.stringify(catalog, null, 2));
+    return { reused, missing: [...new Set(missing)] };
+}
+/**
+ * The saved image for a capture: in the plan's capture directory, or by its
+ * base name at the project root where the browser tool put it, in which case
+ * it is moved into the capture directory first. Nothing outside those two
+ * places is ever read.
+ */
+async function locateCapture(directory, root, file) {
+    const inDirectory = await safeChild(directory, file);
+    if (inDirectory)
+        return inDirectory;
+    const name = basename(file);
+    if (!/^[\w.-]+\.png$/i.test(name))
+        return undefined;
+    const stray = await safeChild(root, name);
+    if (!stray)
+        return undefined;
+    const moved = join(directory, name);
+    try {
+        await rename(stray, moved);
+        return moved;
+    }
+    catch {
+        return stray;
+    }
+}
+/** The real path of `file` when it is an existing file directly inside `parent`. */
+async function safeChild(parent, file) {
+    try {
+        const target = await realpath(resolve(parent, file));
+        const inside = relative(await realpath(parent), target);
+        if (!inside || inside.startsWith('..') || inside.startsWith('/'))
+            return undefined;
+        return target;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=planning-captures.js.map

package/dist/planning-research.d.ts

@@ -0,0 +1,135 @@
+import type { CaptureAuthMode } from './capture-auth.js';
+import { type DocumentationDiscoveryInventory } from './source-discovery.js';
+import type { AgentName, DocumentationPlan, DoxloopProject } from './types.js';
+/**
+ * Planning research: the reading, browsing, and auditing that used to happen
+ * inside one long planning session now runs as short sessions, several at a
+ * time, each returning a compact brief. A separate synthesis session writes
+ * the plan from the briefs. Every brief is checkpointed under the plan, so a
+ * failed or retried plan repeats only the work that is missing.
+ */
+export declare const DEFAULT_PLANNING_PARALLEL = 2;
+/** Crawled pages one existing-documentation research session reads. */
+export declare const EXISTING_DOCS_SHARD_PAGES = 20;
+export type ResearchKind = 'product' | 'application' | 'existing-docs';
+export interface ResearchShard {
+    source: string;
+    /** Snapshot directory, relative to the project root as configured. */
+    snapshotPath: string;
+    pages: Array<{
+        file: string;
+        title: string;
+        words: number;
+    }>;
+    index: number;
+    total: number;
+}
+export interface ResearchTask {
+    id: string;
+    kind: ResearchKind;
+    label: string;
+    /** Whether the session needs the capture browser. */
+    browser: boolean;
+    shard?: ResearchShard;
+    /** Existing pages a page-scoped update names; the product audit reads only the surface behind them. */
+    focus?: string[];
+}
+export interface ResearchBrief {
+    task: string;
+    kind: ResearchKind;
+    label: string;
+    content: unknown;
+}
+export interface ResearchCheckpoint extends ResearchBrief {
+    key: string;
+    repairs?: string[];
+    savedAt: string;
+}
+/** Staged planning is on unless `DOXLOOP_PLANNING_STAGED` turns it off. */
+export declare function stagedPlanningEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** How many research sessions run at once (`DOXLOOP_PLANNING_PARALLEL`, default 3). */
+export declare function planningParallelism(env?: NodeJS.ProcessEnv): number;
+/**
+ * Which research sessions this plan needs: one product-surface audit when
+ * code or specification sources are configured, one application exploration
+ * when screenshots are wanted and an application is configured, and one
+ * existing-documentation audit per shard of crawled pages. The plan's
+ * research scope (see planning-triage) narrows that: a navigation-only
+ * update researches nothing, and a page-scoped update audits only the
+ * product surface behind the named pages, exploring the application only
+ * when screenshots are required.
+ */
+export declare function researchTasks(root: string, project: Pick<DoxloopProject, 'sources' | 'application'>, current: Pick<DocumentationPlan, 'execution' | 'research'>): Promise<ResearchTask[]>;
+export interface ResearchPromptContext {
+    captureDirectory?: string;
+    project: DoxloopProject;
+    current: Pick<DocumentationPlan, 'request' | 'mode' | 'scope' | 'execution'>;
+    discovery: DocumentationDiscoveryInventory;
+    /** Deterministic source-change summary. */
+    changes: string;
+    captureAuth: CaptureAuthMode;
+}
+/** Browser calls one application research session may spend; a session without a budget made a hundred. */
+export declare const APPLICATION_BROWSER_CALLS = 30;
+export declare function researchPrompt(task: ResearchTask, context: ResearchPromptContext): string;
+/** The brief a research session returned, or the reason it could not be read. */
+export declare function readBriefOutput(raw: string, agent: AgentName, task: ResearchTask, prompt?: string): {
+    content: unknown;
+    repairs: string[];
+};
+/** What the synthesis session reads instead of the sources, application, and pages. */
+export declare function formatResearchBriefs(briefs: readonly ResearchBrief[]): string;
+/**
+ * Briefs depend on the sources, the capture intent, the agent, and the
+ * research focus, not on the plan's wording or identity: a revision reuses
+ * them, and so does a later plan on unchanged sources (see
+ * `readResearchCheckpoint`). A page-scoped audit is keyed by its pages.
+ */
+export declare function researchCheckpointKey(current: Pick<DocumentationPlan, 'execution' | 'research'>, sourceSnapshot: string, focus?: readonly string[] | null): string;
+/**
+ * Keys a saved brief may carry to serve this plan: its own key first, then
+ * the key of a full product audit on the same sources, which covers
+ * anything a page-scoped audit would find.
+ */
+export declare function researchCheckpointKeys(current: Pick<DocumentationPlan, 'execution' | 'research'>, sourceSnapshot: string): string[];
+/**
+ * The brief saved for this task under one of `keys`: this plan's own first,
+ * then the newest other plan's. Sources that have not changed since another
+ * plan audited them do not need auditing again, and a second update on the
+ * same snapshot used to redo every session. The application brief is the
+ * exception: it names captures saved under its own plan, which this plan
+ * cannot embed, so it is only ever reused from this plan.
+ */
+export declare function readResearchCheckpoint(root: string, planId: string, task: ResearchTask, keys: string | readonly string[]): Promise<(ResearchCheckpoint & {
+    planId: string;
+}) | undefined>;
+/** Briefs saved for these tasks under one of the keys; empty unless every task has one. */
+export declare function savedResearchBriefs(root: string, planId: string, tasks: readonly ResearchTask[], keys: string | readonly string[]): Promise<ResearchBrief[]>;
+export declare function writeResearchCheckpoint(root: string, planId: string, checkpoint: Omit<ResearchCheckpoint, 'savedAt'>): Promise<void>;
+export interface RunResearchOptions {
+    root: string;
+    planId: string;
+    /** Key the briefs this run saves carry. */
+    key: string;
+    /** Keys a saved brief may carry to be reused; defaults to `key` alone. */
+    acceptKeys?: readonly string[];
+    agent: AgentName;
+    concurrency: number;
+    context: ResearchPromptContext;
+    /** Run one session and return its raw output. */
+    runSession: (task: ResearchTask, prompt: string) => Promise<string>;
+    /** Called as tasks finish, for stage progress. */
+    onProgress?: (done: number, total: number, task: ResearchTask, outcome: 'cached' | 'completed' | 'failed') => void;
+    log?: (line: string) => void;
+}
+/**
+ * Run every research task that has no valid checkpoint, at most
+ * `concurrency` at a time. A session that fails or returns an unreadable
+ * brief is tried once more in a fresh session; the pool keeps going so the
+ * other briefs are saved, then the first failure is reported.
+ */
+export declare function runResearch(tasks: readonly ResearchTask[], options: RunResearchOptions): Promise<{
+    briefs: ResearchBrief[];
+    repairs: string[];
+}>;
+//# sourceMappingURL=planning-research.d.ts.map