feat: enhance scientific writing tests with page budget management

- Added tests to validate the use of target_main_pages and minimum_main_pages in the page budget manager.
- Updated existing tests to reflect changes in the scientific writing policy.

feat: improve state graph runtime tests for usage tracking and budget management

- Introduced tests to accumulate successful node usage and persist it.
- Added tests for handling failed nodes and budget constraints during execution.
- Enhanced existing tests to ensure proper rollback behavior and budget guard functionality.

feat: extend terminal app plan execution tests for feedback handling

- Added tests to verify the correct handling of feedback and critique during plan execution.

feat: enhance write paper PDF build tests for page budget validation

- Updated tests to include validation for minimum and target main pages in compiled page validation.
- Added new tests to ensure proper handling of PDF compilation exceeding target page budgets.

feat: implement model pricing logic for LLM clients

- Introduced model pricing logic to compute usage costs based on token consumption.
- Added tests to validate the pricing propagation for OpenAI and Codex models.

feat: create event logging and replay functionality

- Implemented a persisted event stream for logging run events and replaying them.

test: add comprehensive tests for model pricing and usage computation

- Created tests to ensure correct resolution of model billing and computation of usage costs.

Author: lhy0718

README.md

@@ -310,6 +310,8 @@ Briefs carry **core** sections (topic, objective metric) and **governance** sect
 
 </details>
 
+When `## Manuscript Format` is used, `main_body_pages` is treated as the nominal main-body page target, not a hard upper cap. In config, prefer `paper_profile.target_main_pages` and `paper_profile.minimum_main_pages`; the legacy `paper_profile.main_page_limit` field remains as a compatibility alias during migration.
+
 ---
 
 ## Governance Artifact Flow

docs/architecture.md

@@ -70,6 +70,12 @@ Top-level progression to paper-writing behavior should preserve the distinction
 
 A paper-scale outcome requires evidence beyond successful orchestration, including baseline/comparator presence, real experiment execution, quantitative comparison, and claim-to-evidence linkage.
 
+Page-budget semantics should also remain explicit:
+
+- `paper_profile.target_main_pages` drives main-body writing budgets
+- `paper_profile.minimum_main_pages` gates the compiled-PDF floor check
+- legacy `paper_profile.main_page_limit` is only a compatibility alias during migration and should not be treated as a hard maximum
+
 ## 6) Research brief contract
 
 A governed run should begin from a research brief that defines the execution contract.

docs/paper-quality-bar.md

@@ -54,6 +54,13 @@ After drafting, `write_paper` emits a post-draft critique that can:
 
 In that case the correct action is upstream repair/backtrack, not spending drafting or PDF-compilation effort on a manuscript that should still be blocked.
 
+### Page-budget semantics
+`write_paper` should treat page budgets as explicit targets/floors, not as an implicit upper cap:
+
+- `paper_profile.target_main_pages` is the nominal main-body target used for writing budgets
+- `paper_profile.minimum_main_pages` is the compiled-PDF floor checked after LaTeX build
+- legacy `paper_profile.main_page_limit` remains a compatibility alias and should not be interpreted as a maximum-page constraint
+
 ## 4) Venue-style targeting
 Users can select a target venue style via `paper_profile.target_venue_style` in config.
 Supported venues: `acl`, `aaai`, `icml`, `neurips`, `iclr`, `generic_nlp_conference`, `generic_ml_conference`, `generic_cs_paper`.

docs/research-brief-template.md

@@ -47,6 +47,20 @@ Recommended:
 6. analyze results
 7. draft only after evidence is sufficient
 
+## Manuscript Format
+Optional manuscript-format targets for writing and validation.
+
+Recommended:
+- columns: 1 or 2
+- main_body_pages: nominal target page count for the main body
+- references_excluded_from_page_limit: true/false
+- appendices_excluded_from_page_limit: true/false
+
+Important:
+- `main_body_pages` is a page-budget target, not a hard upper cap.
+- AutoLabOS uses it to size writing budgets and, unless overridden, as the minimum compiled main-body page floor.
+- If the compiled PDF lands below that floor, the page-budget check warns or fails depending on validation mode.
+
 ## Research Question
 Write one clear research question that could be answered by a small real experiment.
 
@@ -194,4 +208,4 @@ Examples:
 - Is the dataset too small to support the claim?
 - Is the proposed comparison fair?
 - Are we relying too much on abstract-only papers?
-- Could a simpler baseline already dominate?
+- Could a simpler baseline already dominate?

src/config.ts

@@ -268,6 +268,8 @@ function buildConfigFromWizardAnswers(answers: {
       venue_style: "acl_long",
       target_venue_style: "generic_cs_paper",
       column_count: 2,
+      target_main_pages: 8,
+      minimum_main_pages: 8,
       main_page_limit: 8,
       references_counted: false,
       appendix_allowed: true,
@@ -686,7 +688,8 @@ function normalizeLoadedConfig(config: AppConfig): AppConfig {
   config.workflow = {
     mode: "agent_approval",
     wizard_enabled: true,
-    approval_mode: normalizeWorkflowApprovalMode(config.workflow.approval_mode)
+    approval_mode: normalizeWorkflowApprovalMode(config.workflow.approval_mode),
+    budget_guard_usd: normalizeBudgetGuardUsd(config.workflow.budget_guard_usd)
   };
   config.experiments = {
     runner: "local_python",
@@ -819,12 +822,23 @@ function normalizeWorkflowApprovalMode(value: unknown): WorkflowApprovalMode {
   return value === "manual" ? "manual" : "minimal";
 }
 
+function normalizeBudgetGuardUsd(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function normalizePaperProfilePageCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(1, Math.round(value)) : undefined;
+}
+
 function normalizePaperProfileConfig(value: AppConfig["paper_profile"] | undefined): AppConfig["paper_profile"] {
   const preferAppendixFor = Array.isArray(value?.prefer_appendix_for)
     ? value?.prefer_appendix_for
         .filter((item): item is string => typeof item === "string" && item.trim().length > 0)
         .map((item) => item.trim())
     : [];
+  const legacyMainPageLimit = normalizePaperProfilePageCount(value?.main_page_limit);
+  const targetMainPages = normalizePaperProfilePageCount(value?.target_main_pages) ?? legacyMainPageLimit ?? 8;
+  const minimumMainPages = normalizePaperProfilePageCount(value?.minimum_main_pages) ?? legacyMainPageLimit ?? targetMainPages;
   const estimatedWordsPerPage =
     typeof value?.estimated_words_per_page === "number" && Number.isFinite(value.estimated_words_per_page)
       ? Math.max(250, Math.round(value.estimated_words_per_page))
@@ -834,10 +848,9 @@ function normalizePaperProfileConfig(value: AppConfig["paper_profile"] | undefin
     venue_style: value?.venue_style?.trim() || "acl_long",
     target_venue_style: value?.target_venue_style?.trim() || undefined,
     column_count: value?.column_count === 1 ? 1 : 2,
-    main_page_limit:
-      typeof value?.main_page_limit === "number" && Number.isFinite(value.main_page_limit)
-        ? Math.max(1, Math.round(value.main_page_limit))
-        : 8,
+    target_main_pages: targetMainPages,
+    minimum_main_pages: minimumMainPages,
+    main_page_limit: minimumMainPages,
     references_counted: Boolean(value?.references_counted),
     appendix_allowed: value?.appendix_allowed !== false,
     appendix_format: value?.appendix_format === "single_column" ? "single_column" : "double_column",

src/core/agents/paperWriterSessionManager.ts

@@ -814,7 +814,8 @@ function buildOutlinePrompt(bundle: PaperWritingBundle, paperProfile?: PaperProf
       ? [
           `Venue style: ${paperProfile.venue_style}`,
           `Column count: ${paperProfile.column_count ?? 2}`,
-          `Main page limit: ${paperProfile.main_page_limit}`,
+          `Target main pages: ${paperProfile.target_main_pages ?? paperProfile.main_page_limit ?? "unknown"}`,
+          `Minimum main pages: ${paperProfile.minimum_main_pages ?? paperProfile.main_page_limit ?? "unknown"}`,
           `References counted toward limit: ${paperProfile.references_counted}`,
           `Appendix allowed: ${paperProfile.appendix_allowed}`,
           `Appendix preferences: ${(paperProfile.prefer_appendix_for || []).join(", ") || "none"}`

src/core/analysis/llmPaperQualityEvaluator.ts

@@ -14,7 +14,7 @@
  * about hard blocks, but the LLM cannot override them.
  */
 
-import type { LLMClient } from "../llm/client.js";
+import type { LLMClient, LLMCompletionUsage } from "../llm/client.js";
 import type { ReviewArtifactPresence } from "../reviewSystem.js";
 import type { AnalysisReport } from "../resultAnalysis.js";
 import type { MinimumGateResult } from "./paperMinimumGate.js";
@@ -194,7 +194,7 @@ export async function runLLMPaperQualityEvaluation(
   input: LLMEvaluatorInput,
   llm: LLMClient,
   opts?: { abortSignal?: AbortSignal; timeoutMs?: number }
-): Promise<{ evaluation: PaperQualityEvaluation; llmUsed: boolean; costUsd?: number }> {
+): Promise<{ evaluation: PaperQualityEvaluation; llmUsed: boolean; costUsd?: number; usage?: LLMCompletionUsage }> {
   const timeoutMs = opts?.timeoutMs ?? 30_000;
 
   try {
@@ -246,7 +246,8 @@ export async function runLLMPaperQualityEvaluation(
         minimum_gate_ceiling: input.minimumGate.ceiling_type
       },
       llmUsed: true,
-      costUsd: completion.usage?.costUsd
+      costUsd: completion.usage?.costUsd,
+      usage: completion.usage
     };
   } catch {
     return { evaluation: buildFallbackEvaluation(input), llmUsed: false };

src/core/analysis/scientificWriting.ts

@@ -1,6 +1,6 @@
 import YAML from "yaml";
 
-import type { PaperProfileConfig } from "../../types.js";
+import type { PaperProfileConfig, ResolvedPaperProfileConfig } from "../../types.js";
 import type { ObjectiveMetricEvaluation, ObjectiveMetricProfile } from "../objectiveMetric.js";
 import type { ConstraintProfile } from "../runConstraints.js";
 import type {
@@ -216,6 +216,9 @@ export interface SectionBudgetEntry {
 export interface PageBudgetManagerReport {
   venue_style: string;
   column_count: 1 | 2;
+  target_main_pages: number;
+  minimum_main_pages: number;
+  /** @deprecated Compatibility alias for minimum_main_pages. */
   main_page_limit: number;
   references_counted: boolean;
   appendix_allowed: boolean;
@@ -398,6 +401,8 @@ export interface WritePaperGateDecision {
 const DEFAULT_PAPER_PROFILE: PaperProfileConfig = {
   venue_style: "acl_long",
   column_count: 2,
+  target_main_pages: 8,
+  minimum_main_pages: 8,
   main_page_limit: 8,
   references_counted: false,
   appendix_allowed: true,
@@ -415,7 +420,7 @@ const DEFAULT_PAPER_PROFILE: PaperProfileConfig = {
 export function resolvePaperProfile(
   profile: Partial<PaperProfileConfig> | undefined,
   constraintProfile?: ConstraintProfile
-): PaperProfileConfig {
+): ResolvedPaperProfileConfig {
   const preferAppendixFor = Array.isArray(profile?.prefer_appendix_for)
     ? profile?.prefer_appendix_for
         .filter((item): item is string => typeof item === "string" && item.trim().length > 0)
@@ -430,17 +435,28 @@ export function resolvePaperProfile(
         ? "acl_short"
         : "acl_long"
       : DEFAULT_PAPER_PROFILE.venue_style);
-  const inferredPageLimit =
+  const legacyMainPageLimit =
     typeof profile?.main_page_limit === "number" && Number.isFinite(profile.main_page_limit)
       ? Math.max(1, Math.round(profile.main_page_limit))
-      : /\bshort\b/iu.test(lengthHint)
-        ? 4
-        : DEFAULT_PAPER_PROFILE.main_page_limit;
+      : undefined;
+  const inferredTargetMainPages =
+    typeof profile?.target_main_pages === "number" && Number.isFinite(profile.target_main_pages)
+      ? Math.max(1, Math.round(profile.target_main_pages))
+      : legacyMainPageLimit
+        ?? (/\bshort\b/iu.test(lengthHint) ? 4 : (DEFAULT_PAPER_PROFILE.target_main_pages || 8));
+  const inferredMinimumMainPages =
+    typeof profile?.minimum_main_pages === "number" && Number.isFinite(profile.minimum_main_pages)
+      ? Math.max(1, Math.round(profile.minimum_main_pages))
+      : legacyMainPageLimit
+        ?? inferredTargetMainPages;
 
   return {
     venue_style: inferredVenueStyle,
+    target_venue_style: cleanString(profile?.target_venue_style) || DEFAULT_PAPER_PROFILE.target_venue_style,
     column_count: profile?.column_count === 1 ? 1 : DEFAULT_PAPER_PROFILE.column_count,
-    main_page_limit: inferredPageLimit,
+    target_main_pages: inferredTargetMainPages,
+    minimum_main_pages: inferredMinimumMainPages,
+    main_page_limit: legacyMainPageLimit ?? inferredMinimumMainPages,
     references_counted:
       typeof profile?.references_counted === "boolean"
         ? profile.references_counted
@@ -847,7 +863,7 @@ export function pageBudgetManager(input: {
 }): PageBudgetManagerReport {
   const profile = resolvePaperProfile(input.profile);
   const estimatedWordsPerPage = profile.estimated_words_per_page || 420;
-  const targetMainWords = profile.main_page_limit * estimatedWordsPerPage;
+  const targetMainWords = profile.target_main_pages * estimatedWordsPerPage;
   const minimumMainWords = Math.round(targetMainWords * 0.62);
   const maximumMainWords = Math.round(targetMainWords * 1.15);
   const estimatedMainWords = estimateDraftWords(input.draft.sections);
@@ -877,7 +893,7 @@ export function pageBudgetManager(input: {
   const warnings: string[] = [];
   if (estimatedMainWords < Math.round(targetMainWords * 0.55)) {
     warnings.push(
-      `Estimated main-body length (${estimatedMainWords} words) is far below the ${profile.main_page_limit}-page target budget.`
+      `Estimated main-body length (${estimatedMainWords} words) is far below the ${profile.target_main_pages}-page target budget.`
     );
   } else if (estimatedMainWords < minimumMainWords) {
     warnings.push(
@@ -894,6 +910,8 @@ export function pageBudgetManager(input: {
   return {
     venue_style: profile.venue_style,
     column_count: profile.column_count,
+    target_main_pages: profile.target_main_pages,
+    minimum_main_pages: profile.minimum_main_pages,
     main_page_limit: profile.main_page_limit,
     references_counted: profile.references_counted,
     appendix_allowed: profile.appendix_allowed,
@@ -3068,7 +3086,7 @@ export function buildScientificValidationArtifact(input: ScientificDraftResult):
       finding: input.evidence_diagnostics.blocked_by_evidence_insufficiency ? "unverifiable" : "repairable",
       message:
         input.page_budget.warnings[0]
-        || `Main-body length remains below the venue-aware ${input.page_budget.main_page_limit}-page target.`,
+        || `Main-body length remains below the venue-aware ${input.page_budget.target_main_pages}-page target.`,
       details: input.page_budget.warnings.slice(1),
       thin_sections: input.evidence_diagnostics.thin_sections,
       missing_evidence_categories: input.evidence_diagnostics.missing_evidence_categories,

src/core/doctor.ts

@@ -37,6 +37,8 @@ interface RunsFileSnapshot {
 
 interface CompiledPageValidationSnapshot {
   status?: string;
+  minimum_main_pages?: number;
+  target_main_pages?: number;
   main_page_limit?: number;
   compiled_pdf_page_count?: number | null;
   message?: string;
@@ -234,13 +236,23 @@ async function loadLatestPaperPageBudgetCheck(workspaceRoot: string): Promise<Do
   const status = validation.status === "pass" ? "pass" : validation.status === "warn" ? "warn" : "fail";
   const pageCount =
     typeof validation.compiled_pdf_page_count === "number" ? String(validation.compiled_pdf_page_count) : "unknown";
-  const limit = typeof validation.main_page_limit === "number" ? String(validation.main_page_limit) : "unknown";
+  const minimumMainPages = typeof validation.minimum_main_pages === "number"
+    ? String(validation.minimum_main_pages)
+    : typeof validation.main_page_limit === "number"
+      ? String(validation.main_page_limit)
+      : "unknown";
+  const targetMainPages = typeof validation.target_main_pages === "number"
+    ? String(validation.target_main_pages)
+    : typeof validation.main_page_limit === "number"
+      ? String(validation.main_page_limit)
+      : "unknown";
   return {
     name: "paper-page-budget",
     ok: status === "pass",
     detail:
       `Latest compiled paper page-budget check for run ${latestRun.id}: ${status}. ` +
-      `pages=${pageCount}, main_page_limit=${limit}. ${validation.message || ""}`.trim()
+      `pages=${pageCount}, minimum_main_pages=${minimumMainPages}, target_main_pages=${targetMainPages}. ` +
+      `${validation.message || ""}`.trim()
   };
 }