agent-nuvira 3.1.3 → 3.3.0

package/dist/learning/long-form.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Long-form execution — bounded units + a progress ledger for deliverables
+ * that are larger than one LLM generation (enterprise-grade hardening, G8).
+ *
+ * WHY THIS EXISTS (the WhatsApp story audit):
+ * The user asked for a 100-page story. Two facts made that ask IMPOSSIBLE for
+ * any of the 507 eligible models, independently of the model-shortage myth the
+ * failure message told:
+ *
+ *   1. The code writer generates with `maxTokens: 2048` — about 1,500 words,
+ *      roughly 4–5 pages. A 100-page book is ~35,000 words, i.e. 25–40 times
+ *      the largest artifact the pipeline could ever emit.
+ *   2. Nothing in the pipeline decomposed the ask. The plan was 4 steps, none
+ *      of which produced prose, and no component counted words or pages, so
+ *      there was no notion of "partially done" and nothing to resume.
+ *
+ * So the fix is structural, not a bigger prompt: split the work into bounded
+ * units that fit one generation, persist progress per unit, and report honest
+ * completion ("chapter 7 of 39"). This module owns the arithmetic and the
+ * ledger; the writer owns one unit at a time.
+ *
+ * WHY UNIT FILES, NOT APPENDS TO ONE FILE:
+ * The obvious design — append each chapter to `Mahagatha.md` — requires the
+ * writer to rewrite the whole file every unit (the FileChange contract is a
+ * full-content write). By chapter 35 that is ~35k words of input tokens per
+ * generation, which does not fit the context window it was going to be
+ * generated from. One file per unit keeps every generation bounded and makes
+ * the work genuinely resumable. The single document the user asked for is
+ * ASSEMBLED deterministically (pure string concatenation, no LLM, no cost)
+ * once the units are done.
+ *
+ * Storage: `~/.nuvira/memory/long-form.json`, keyed by project + document.
+ * Honours `NUVIRA_MEMORY_DIR` / `BUFF_MEMORY_DIR` like the other ledgers.
+ * Every write is best-effort — the ledger must NEVER break a turn.
+ */
+/**
+ * Words per printed page. 350 is the standard estimate for a 12pt manuscript
+ * page (double-spaced manuscript convention is ~250; a typeset book page is
+ * ~350–400). Erring low keeps the plan honest: a "100-page" target that lands
+ * at 35,000 words is comfortably 100 pages, never short of it.
+ */
+export declare const WORDS_PER_PAGE = 350;
+/**
+ * Words per generation unit. Sized to land inside a raised output cap with
+ * headroom for the model to finish a sentence: 900 words ≈ 1,400 tokens,
+ * comfortably under a 2,048-token floor and well within a 4k–8k cap. Larger
+ * units risk truncation, which is exactly how the original writer failed
+ * ("no parseable output" on a truncated response).
+ */
+export declare const WORDS_PER_GENERATION = 900;
+/** Words per chapter when the user counts chapters instead of pages. */
+export declare const WORDS_PER_CHAPTER = 2500;
+/**
+ * Units planned per turn. A 100-page book is ~39 units; planning all of them
+ * as orchestrator steps would build a plan the run could never finish, and a
+ * single-run attempt is precisely the "bigger ask" the agent kept losing.
+ * Bounded batches let each turn end with CONCRETE delivered text and a
+ * recorded progress line, and the next turn resumes where it stopped.
+ */
+export declare const MAX_UNITS_PER_RUN = 4;
+/** The unit the user counted in. */
+export type LongFormUnit = 'pages' | 'words' | 'chapters' | 'sections';
+/** A parsed long-form target derived from the goal. */
+export interface LongFormTarget {
+    /** What the user counted in ("100 pages"). */
+    unit: LongFormUnit;
+    /** How many of `unit` they asked for. */
+    amount: number;
+    /** Total words the finished deliverable should reach. */
+    wordsTarget: number;
+    /** How the work is split into generations. */
+    unitCount: number;
+    /** Where the number came from, for auditability. */
+    source: string;
+}
+/** One bounded unit of work (a chapter/section). */
+export interface SectionProgress {
+    /** 1-based position. */
+    index: number;
+    /** Display title ("Chapter 3"). */
+    title: string;
+    /** Path of this unit's file, relative to the project root. */
+    path: string;
+    /** Words this unit should aim for. */
+    targetWords: number;
+    status: 'pending' | 'done' | 'failed';
+    /** Words actually produced (measured from the file when present). */
+    words: number;
+    /** Generation attempts spent on this unit. */
+    attempts: number;
+    lastError?: string;
+}
+/** The persisted job: everything needed to resume the work in a later turn. */
+export interface LongFormJob {
+    /** Ledger key: project path + document path. */
+    key: string;
+    /** The original goal, so a resumed turn re-states intent faithfully. */
+    goal: string;
+    /** Absolute project root. */
+    projectPath: string;
+    /** The document the user actually asked for (assembled at the end). */
+    docPath: string;
+    /** 'creative' | 'document' — drives titling and the writer's prompt. */
+    deliverableClass: 'creative' | 'document';
+    target: LongFormTarget;
+    sections: SectionProgress[];
+    /** Words across every DONE unit. */
+    words: number;
+    status: 'in_progress' | 'done';
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Extract the long-form target from a goal, or `null` when the goal does not
+ * name a magnitude (in which case the ask fits one generation and this module
+ * stays out of the way).
+ *
+ * Understands the shapes users actually type — "a 100 page story", "100-page
+ * book", "in 12 chapters", "about 5000 words", "10 पेज", "एक उपन्यास जिसमें 8
+ * अध्याय हों" — and prefers the most specific unit named.
+ */
+export declare function parseLongFormTarget(goal: string): LongFormTarget | null;
+/** Default display title for a unit, by class. */
+export declare function sectionTitle(cls: 'creative' | 'document', index: number): string;
+/**
+ * Build the unit list for a target. Word targets are distributed evenly with
+ * the remainder spread over the first units, so the SUM of unit targets always
+ * equals the overall word target — the plan cannot silently undershoot the ask.
+ */
+export declare function planSections(target: LongFormTarget, cls: 'creative' | 'document', dir?: string): SectionProgress[];
+/** Pages implied by a word count (for progress reporting). */
+export declare function estimatePages(words: number): number;
+/** Stable key for a (project, document) pair. */
+export declare function longFormKey(projectPath: string, docPath: string): string;
+/** Both `chapters/03-chapter-3.md` (relative) and absolute path forms. */
+export declare function sectionAbsolutePath(projectPath: string, sectionPath: string): string;
+/**
+ * Start a job, or RESUME an existing one for the same document.
+ *
+ * Resuming is the whole point: the failing session re-derived the same plan
+ * six times and lost every partial result. A resumed job keeps its existing
+ * units, their statuses and their word counts, so the caller can ask for the
+ * next pending batch and make real forward progress per turn.
+ */
+export declare function startOrResumeJob(input: {
+    projectPath: string;
+    docPath: string;
+    goal: string;
+    target: LongFormTarget;
+    deliverableClass: 'creative' | 'document';
+    dir?: string;
+}): {
+    job: LongFormJob;
+    resumed: boolean;
+};
+/** Read a job without creating one. */
+export declare function getJob(projectPath: string, docPath: string): LongFormJob | null;
+/**
+ * The most recently updated job for a project REGARDLESS of status, or null.
+ *
+ * The unattended runner needs this: after the last batch completes the job it
+ * must be able to read the FINISHED record to confirm the document exists, and
+ * `findInProgressJob` (correctly) hides those.
+ */
+export declare function findLatestJob(projectPath: string): LongFormJob | null;
+/**
+ * The most recently updated UNFINISHED job for a project, or null.
+ *
+ * WHY: a follow-up turn says "continue" — which names no document, no length,
+ * and no class. Re-deriving the job from that text would land on the default
+ * filename and start a SECOND book from scratch, which is the "agent goes in a
+ * loop and never delivers" behaviour this ledger exists to end. The in-flight
+ * job for this project is the correct target for a continuation.
+ */
+export declare function findInProgressJob(projectPath: string): LongFormJob | null;
+/** Number of words in a body of text (whitespace-delimited). */
+export declare function countWords(text: string): number;
+/**
+ * Record the outcome of ONE unit.
+ *
+ * `ok` requires actual content: a unit whose file is missing or empty is a
+ * FAILURE even if the writer reported success. That is the G10 principle
+ * applied to long-form work — "the step ran" is not "the work exists".
+ */
+export declare function recordSectionOutcome(job: LongFormJob, index: number, outcome: {
+    ok: boolean;
+    words?: number;
+    error?: string;
+}): LongFormJob;
+/**
+ * Persist a job that the caller has already mutated (e.g. after writing unit
+ * files). Kept separate from `recordSectionOutcome` so batch callers write
+ * once instead of once per unit.
+ */
+export declare function saveJob(job: LongFormJob): void;
+/**
+ * The next pending units to execute — bounded per run so a turn always ends
+ * with delivered text rather than an unfinished marathon.
+ */
+export declare function nextPendingSections(job: LongFormJob, limit?: number): SectionProgress[];
+/** Progress snapshot for reporting. */
+export interface LongFormProgress {
+    done: number;
+    total: number;
+    words: number;
+    wordsTarget: number;
+    pages: number;
+    pagesTarget: number;
+    percent: number;
+    complete: boolean;
+}
+export declare function jobProgress(job: LongFormJob): LongFormProgress;
+/**
+ * The honest progress line — reported to the user every turn.
+ *
+ * Deliberately quotes BOTH the unit count and the words, because the user
+ * asked in pages and a word count alone would look like a dodge. This is the
+ * sentence the original session could never produce: it had no idea how much
+ * of the book existed.
+ */
+export declare function formatProgress(job: LongFormJob): string;
+/** The next `limit` units as a plan the writer can execute one at a time. */
+export declare function nextUnitBrief(job: LongFormJob, limit?: number): Array<{
+    index: number;
+    title: string;
+    path: string;
+    targetWords: number;
+    /** Continuity: the previous unit's tail, so the prose joins up. */
+    previousTail: string;
+}>;
+/** Last `chars` of a file, or '' when it does not exist. */
+export declare function readTail(absolutePath: string, chars: number): string;
+export interface AssemblyResult {
+    path: string;
+    files: number;
+    words: number;
+    pages: number;
+}
+/**
+ * Deterministically assemble the finished document from its unit files.
+ *
+ * Pure concatenation — no LLM, no cost, no drift. Runs only when every unit is
+ * done, so the assembled document is never a half-book presented as complete.
+ * Returns null when the job is not finished (the caller must not claim
+ * completion, and must keep reporting progress instead).
+ */
+export declare function assembleDocument(job: LongFormJob): AssemblyResult | null;
+/** Relative path display, for a concise log line. */
+export declare function displayPath(projectPath: string, absolute: string): string;
+/** Test/reset hook: forget every job. */
+export declare function clearLongFormJobs(): void;
+//# sourceMappingURL=long-form.d.ts.map

package/dist/learning/long-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-form.d.ts","sourceRoot":"","sources":["../../src/learning/long-form.ts"],"names":[],"mappings":"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"}