@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/author.d.ts

@@ -1,10 +1,31 @@
-import type { AgentName, ApplicationConfig, DocumentationBrief, GeneratorName, SourceBinding } from './types.js';
+export { ClaudeStreamLogFormatter, CodexStreamLogFormatter, GeminiStreamLogFormatter } from './agent-log.js';
+import { type CaptureAuthMode } from './capture-auth.js';
+import { type ScreenCaptureProvider } from './screen-capture-provider.js';
+import type { AgentName, AgentUsage, ApplicationConfig, DocumentationBrief, DocumentationPlan, DocumentationPlanPage, DoxloopProject, GeneratorName, SourceBinding } from './types.js';
 export type AuthorMode = 'create' | 'update' | 'review';
 export type ScreenshotIntent = 'auto' | 'enabled' | 'disabled';
 export declare function resolveScreenshotIntent(enabled: boolean, disabled: boolean): ScreenshotIntent;
-declare const REASONING_LEVELS: readonly ["minimal", "low", "medium", "high", "xhigh"];
+declare const REASONING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
 export type ReasoningLevel = (typeof REASONING_LEVELS)[number];
+declare const CLAUDE_EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type ClaudeEffortLevel = (typeof CLAUDE_EFFORT_LEVELS)[number];
 export declare function parseReasoning(value: string | undefined): ReasoningLevel | undefined;
+/** A per-session reasoning level: Claude's effort names or Codex's reasoning names. */
+export type SessionEffort = ReasoningLevel | ClaudeEffortLevel;
+export declare function sessionEffortFromEnvironment(name: string, env?: NodeJS.ProcessEnv): SessionEffort | undefined;
+/**
+ * The agent-specific reasoning options for one session. Claude takes the
+ * effort names; Codex takes the reasoning names, with Claude-only levels
+ * mapped to its nearest ("low" is common to both). Gemini has no switch.
+ */
+export declare function sessionEffortOptions(agent: string, effort: SessionEffort | undefined, run: {
+    reasoning?: ReasoningLevel;
+    effort?: ClaudeEffortLevel;
+}): {
+    reasoning?: ReasoningLevel;
+    effort?: ClaudeEffortLevel;
+};
+export declare function parseClaudeEffort(value: string | undefined): ClaudeEffortLevel | undefined;
 export declare function runAuthor(options: {
     root: string;
     mode: AuthorMode;
@@ -13,20 +34,201 @@ export declare function runAuthor(options: {
     request?: string;
     model?: string;
     reasoning?: ReasoningLevel;
+    effort?: ClaudeEffortLevel;
     screenshots?: ScreenshotIntent;
     changeSummary?: string;
+    nonInteractive?: boolean;
+    timeoutMinutes?: number;
+    /** Claude turn cap for an unattended run; derived from the approved plan when omitted. */
+    maxTurns?: number;
+    /** Claude spending cap in US dollars for an unattended run. Codex and Gemini have no equivalent. */
+    maxBudgetUsd?: number;
+    /** Pages the run is expected to write, for the "N of M" stage counter. Read from the plan when omitted. */
+    plannedPages?: number;
+    /** Stage copy for the page-writing stage, such as "Editing selected pages". */
+    progressLabel?: string;
+    /**
+     * Proposal workspaces are throwaway copies of the project. They must not open
+     * a history database of their own; the real project records the run instead.
+     */
+    recordHistory?: boolean;
+    /**
+     * Scoped page-edit workspaces must not rewrite source-sync metadata. That
+     * metadata is neither part of the requested page change nor an indication
+     * that product-source drift has been reconciled.
+     */
+    recordOperationalState?: boolean;
+    /** Keep a proposal workspace reviewable so validation errors can be fixed
+     * with a follow-up instruction instead of discarding the agent's work. */
+    onFailure?: (detail: string) => void;
+    tolerateValidationErrors?: boolean;
+    /**
+     * Project whose saved sign-in material the capture browser should use.
+     * Proposal workspaces are throwaway copies under `.doxloop/runs`, and the
+     * material is keyed by project path, so a workspace root would find nothing.
+     */
+    captureAuthRoot?: string;
+    /**
+     * Write the approved plan in short batches of fresh agent sessions, with
+     * Doxloop's repairs and validation between them, instead of one long
+     * session. Only unattended runs with a staged plan qualify.
+     */
+    planBatches?: boolean;
+    /** Token usage summed over every agent session of the run. */
+    onUsage?: (usage: AgentUsage) => void;
 }): Promise<number>;
+/**
+ * A create plan often puts a starter page's replacement at a new path
+ * ("getting-started/quickstart" for the scaffold's "quickstart.mdx") with
+ * action "update". Read together with "update existing pages in place", that
+ * left the writer keeping the root file while every link pointed at the
+ * planned path, and the run failed on broken links twice in a row. Say which
+ * file each such page replaces and where it belongs, so nothing is left to
+ * interpretation. The site root's landing page is the one exception: a
+ * Doxbrix site needs its index, so that page is written where the index is.
+ */
+export declare function starterReplacements(root: string, plan: Pick<DocumentationPlan, 'pages'>, existing: readonly string[]): Promise<string>;
 export declare function prepareAgentPrompt(root: string, prompt: string, platform?: NodeJS.Platform): Promise<{
     argument: string;
     path: string | undefined;
 }>;
+/**
+ * Turn caps for Claude in non-interactive runs. A planning run reads sources
+ * and inspects the application; an authoring run writes every approved page
+ * and captures every planned screenshot, so its cap scales with the plan. The
+ * previous fixed cap of 60 stopped a 44-page, 85-screenshot run while it was
+ * still exploring the application, before it had written a single page.
+ */
+export declare const PLANNING_MAX_TURNS = 100;
+/** Tools a planning run must never use: planning proposes, it does not write or run anything. */
+export declare const CLAUDE_PLANNING_DISALLOWED_TOOLS: readonly ["Bash", "Edit", "Write", "MultiEdit", "NotebookEdit"];
+/** Environment for a spawned agent. Claude Code's own reply cap stays in force: a plan that needs more than it is not converging, and a longer cap only makes that failure slower. */
+/**
+ * The environment an unattended agent runs in. `NODE_USE_SYSTEM_CA` makes
+ * every Node process read the macOS Keychain trust store at startup; inside
+ * the agent's sandbox that read is denied and Node dies with
+ * "SecItemCopyMatching failed -67674" before printing anything — so the
+ * writer could never run `doxloop test`, never saw its thin-page warnings,
+ * and either built substitute checks or left the warnings for the reviewer.
+ * The agent's own commands only ever reach the local documentation project,
+ * so the system trust store buys them nothing.
+ */
+export declare function agentEnvironment(_name: AgentName, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const MIN_AUTHORING_MAX_TURNS = 400;
+export declare const EDIT_MIN_MAX_TURNS = 80;
+export declare const EDIT_TURNS_PER_PAGE = 30;
+export declare function authoringTurnBudget(plan: Pick<DocumentationPlan, 'pages'> | undefined): number;
+export interface EditPromptInput {
+    pages: Array<{
+        path: string;
+        title: string;
+    }>;
+    instruction: string;
+    allowRelated: boolean;
+    followUps?: Array<{
+        instruction: string;
+    }>;
+}
+/** Focus the general update prompt on a reviewer-selected set of existing pages. */
+export declare function editPrompt(input: EditPromptInput): string;
+/**
+ * How many times an unattended Claude run resumes its session after a
+ * transient API failure before the run is reported as failed.
+ */
+export declare const DEFAULT_AGENT_API_RESUMES = 2;
+export declare function agentApiResumeLimit(): number;
+/** A short, growing pause before resuming, so a struggling API gets a moment to recover. */
+export declare function agentApiResumeDelayMs(attempt: number): number;
+/** The prompt that continues a Claude session cut off by an API failure. */
+export declare function resumedSessionPrompt(failureDetail: string | undefined): string;
+/** The failure message for a non-zero agent exit, with the reason when Claude reported one. */
+export declare function agentExitMessage(exitCode: number, detail?: string): string;
+/** Shell invocations an unattended Gemini run may make without confirmation. */
+export declare const GEMINI_ALLOWED_TOOLS: readonly ["run_shell_command(doxloop)", "run_shell_command(npx doxloop)", "run_shell_command(pnpm exec doxloop)", "run_shell_command(npm exec doxloop)"];
 export declare function agentArguments(name: AgentName, prompt: string, options?: {
     model?: string;
     reasoning?: ReasoningLevel;
+    effort?: ClaudeEffortLevel;
     mode?: AuthorMode;
+    nonInteractive?: boolean;
+    sourceDirectories?: readonly string[];
+    captureProvider?: ScreenCaptureProvider;
+    captureRequired?: boolean;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    /** Claude session to continue instead of starting a new one. */
+    resumeSession?: string;
+    /**
+     * MCP servers from the user's own Codex config, switched off for an
+     * unattended session so it runs with Doxloop's tools only.
+     */
+    userMcpServers?: readonly string[];
 }): string[];
+/**
+ * Resolve the configured evidence locations that an agent launched from the
+ * documentation project must be allowed to read. Local OpenAPI files grant
+ * only their containing directory; remote specifications need no filesystem
+ * access. Paths already inside the documentation project are omitted.
+ */
+export declare function sourceAccessDirectories(root: string, sources: SourceBinding[]): string[];
+/**
+ * How the writer treats an existing documentation site next to product
+ * sources: product code decides facts, the old documentation decides what
+ * readers were told and where they went to read it. Without code the rewrite
+ * may reorganize and clarify but must not manufacture facts.
+ */
+export declare function existingDocumentationGuidance(sources: SourceBinding[]): string;
 export declare function authorPrompt(mode: AuthorMode, sources: SourceBinding[], request?: string, generator?: GeneratorName, documentation?: DocumentationBrief, designReferences?: Array<{
     url: string;
-}>, changeSummary?: string, screenshots?: ScreenshotIntent, application?: ApplicationConfig): string;
-export {};
+}>, changeSummary?: string, screenshots?: ScreenshotIntent, application?: ApplicationConfig, cliCommand?: string, captureAuth?: CaptureAuthMode, specCopies?: Record<string, string>): string;
+/** Fix rounds Doxloop runs on a batch before leaving remaining issues to the reviewer. */
+export declare const MAX_FIX_ROUNDS: number;
+/**
+ * The skill references every writer batch reads before writing, inlined once
+ * so they arrive as a stable, cacheable prompt prefix instead of six to eight
+ * file reads per session (a real run spent ~70 turns on those reads). Type
+ * playbooks vary by batch and stay with the agent.
+ */
+export declare function skillReferencePrefix(generator: string, screenshots: boolean, root?: string): Promise<{
+    text: string;
+    names: string[];
+}>;
+/** Title and icon from a page's frontmatter, for the batch contract's written-pages summary. */
+export declare function frontmatterSummary(root: string, file: string): Promise<{
+    title?: string;
+    icon?: string;
+}>;
+export declare function sessionPreamble(project: DoxloopProject, sources: SourceBinding[], cliCommand?: string, capture?: string): string;
+/**
+ * What every batched session must know about the capture browser. The
+ * single-session prompt carried this; batched sessions had only the manifest
+ * slice, so a run with saved credentials still gave up at the sign-in page
+ * and recorded every authenticated step as text-only.
+ */
+export declare function batchCaptureText(application: ApplicationConfig, captureAuth: CaptureAuthMode): string;
+/** The task for a session that retakes the screenshots Doxloop found wanting. */
+export declare function retakeContract(defects: string[], progress: string[]): string;
+/** Project-relative page files for planned pages that exist in the workspace. */
+/** What each planned page's file holds before a session, so a session's writes can be told from files that were already there. */
+export declare function snapshotPlanPages(root: string, plan: DocumentationPlan, pages: DocumentationPlanPage[]): Promise<Map<string, string | undefined>>;
+/**
+ * The planned pages of `pages` that no session has written yet: no file in
+ * the workspace, or — given the snapshot taken before the session — a file
+ * (a starter page, an existing page awaiting its update) whose content is
+ * exactly what it was.
+ */
+export declare function unwrittenPlanPages(root: string, plan: DocumentationPlan, pages: DocumentationPlanPage[], before?: Map<string, string | undefined>): Promise<DocumentationPlanPage[]>;
+export declare function planPageFiles(root: string, plan: DocumentationPlan, pages: DocumentationPlanPage[]): Promise<string[]>;
+/**
+ * Planned pages already finished in this workspace — present, no longer
+ * starter content, and free of validation errors — so a resumed or retried
+ * run writes only what is missing instead of everything again.
+ */
+export declare function completedPlanPages(root: string, plan: DocumentationPlan, pages: DocumentationPlanPage[]): Promise<Set<string>>;
+/**
+ * The agent is told how sign-in is handled, never the values. A recorded
+ * session is preloaded into the capture browser; saved credentials are typed
+ * by secret name, which the capture server substitutes and redacts.
+ */
+export declare function captureAuthPrompt(mode: CaptureAuthMode): string;
 //# sourceMappingURL=author.d.ts.map