novelforge-agent 0.1.0

package/dist/src/core/schemas.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+export const CoreCastMemberSchema = z.object({
+    name: z.string().min(1),
+    role: z.string().min(1),
+    description: z.string().min(1),
+});
+export const NovelMetadataSchema = z.object({
+    title: z.string().min(1),
+    genre: z.string().min(1),
+    premise: z.string().min(1),
+    language: z.string().min(1).default('zh-CN'),
+    style: z.string().min(1).default('清晰、连贯、适合长篇连载'),
+    coreCast: z.array(CoreCastMemberSchema).min(1),
+});
+export const VolumeArchitectureSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    summary: z.string().min(1),
+    order: z.number().int().positive(),
+});
+export const ChapterArchitectureSchema = z.object({
+    chapterNumber: z.number().int().positive(),
+    title: z.string().min(1),
+    volumeId: z.string().min(1),
+    summary: z.string().min(1),
+    requiredBeats: z.array(z.string().min(1)).min(1),
+});
+export const ArchitecturePayloadSchema = z.object({
+    full: z.string().min(1),
+    volumes: z.array(VolumeArchitectureSchema).min(1),
+    chapters: z.array(ChapterArchitectureSchema).min(1),
+});
+export const MemoryCardSchema = z.object({
+    summary: z.string().min(1),
+    keyEvents: z.array(z.string().min(1)),
+    entities: z.array(z.object({
+        name: z.string().min(1),
+        type: z.string().min(1),
+        state: z.string().min(1),
+    })),
+    facts: z.array(z.object({
+        subject: z.string().min(1),
+        predicate: z.string().min(1),
+        object: z.string().min(1),
+    })),
+    stateChanges: z.array(z.object({
+        entity: z.string().min(1),
+        before: z.string().min(1),
+        after: z.string().min(1),
+    })),
+    openThreads: z.array(z.string().min(1)),
+});
+export const ContinuityReviewSchema = z.object({
+    range: z.object({
+        start: z.number().int().positive(),
+        end: z.number().int().positive(),
+    }),
+    status: z.enum(['clean', 'issues_found']),
+    issues: z.array(z.object({
+        severity: z.enum(['low', 'medium', 'high']),
+        description: z.string().min(1),
+        evidence: z.string().min(1),
+        suggestion: z.string().min(1),
+    })),
+});
+export const ChapterReviewIssueSchema = z.object({
+    severity: z.enum(['low', 'medium', 'high']),
+    category: z.enum(['character', 'world', 'timeline', 'item', 'knowledge', 'pacing', 'style', 'architecture']),
+    description: z.string().min(1),
+    evidence: z.string().min(1),
+    suggestion: z.string().min(1),
+});
+export const ChapterReviewSchema = z.object({
+    chapterNumber: z.number().int().positive(),
+    status: z.enum(['clean', 'issues_found']),
+    issues: z.array(ChapterReviewIssueSchema),
+});
+export const CrossChapterReviewSchema = z.object({
+    range: z.object({
+        start: z.number().int().positive(),
+        end: z.number().int().positive(),
+    }),
+    status: z.enum(['clean', 'issues_found']),
+    issues: z.array(z.object({
+        severity: z.enum(['low', 'medium', 'high']),
+        chapters: z.array(z.number().int().positive()).min(1),
+        description: z.string().min(1),
+        evidence: z.string().min(1),
+        suggestion: z.string().min(1),
+    })),
+});

package/dist/src/core/steps/architecture.js

@@ -0,0 +1,16 @@
+import { ArchitecturePayloadSchema } from '../schemas.js';
+import { saveJsonFile, saveMarkdownFile } from '../projectStore.js';
+import { parseJson } from './types.js';
+export const architectureHandler = async (state, content) => {
+    const parsed = ArchitecturePayloadSchema.parse(parseJson(content));
+    const savedPaths = [
+        await saveMarkdownFile(state.projectPath, 'architecture/full.md', parsed.full),
+        await saveJsonFile(state.projectPath, 'architecture/volumes.json', parsed.volumes),
+        await saveJsonFile(state.projectPath, 'architecture/chapters.json', parsed.chapters),
+    ];
+    return {
+        savedPaths,
+        fileEntries: { architecture: 'architecture/chapters.json' },
+        next: { kind: 'linear', nextStep: 'chapter' },
+    };
+};

package/dist/src/core/steps/chapter.js

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+import { saveMarkdownFile } from '../projectStore.js';
+import { chapterFileName } from '../fileNames.js';
+import { indexChapter } from '../retrieval/index.js';
+import { requireNonEmpty } from './types.js';
+export const chapterHandler = async (state, content) => {
+    requireNonEmpty(content, 'Chapter Markdown');
+    const relative = join('chapters', chapterFileName(state.currentChapter));
+    const path = await saveMarkdownFile(state.projectPath, relative, content);
+    await indexChapter(state.projectPath, state.currentChapter, content);
+    return {
+        savedPaths: [path],
+        fileEntries: { [`chapter-${state.currentChapter}`]: relative },
+        next: { kind: 'linear', nextStep: 'memory_card' },
+    };
+};

package/dist/src/core/steps/chapterReview.js

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+import { ChapterReviewSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { chapterReviewFileName } from '../fileNames.js';
+import { parseJson } from './types.js';
+export const chapterReviewHandler = async (state, content) => {
+    const parsed = ChapterReviewSchema.parse(parseJson(content));
+    const target = state.pendingAction?.chapterNumber ?? parsed.chapterNumber;
+    const relative = join('reviews/chapter', chapterReviewFileName(target));
+    const path = await saveJsonFile(state.projectPath, relative, parsed);
+    return {
+        savedPaths: [path],
+        fileEntries: { [`review-chapter-${target}`]: relative },
+        next: { kind: 'sideTrackReturn' },
+    };
+};

package/dist/src/core/steps/chapterRevision.js

@@ -0,0 +1,20 @@
+import { join } from 'node:path';
+import { archiveChapterVersion, saveMarkdownFile } from '../projectStore.js';
+import { chapterFileName, chapterVersionFileName } from '../fileNames.js';
+import { indexChapter } from '../retrieval/index.js';
+import { requireNonEmpty } from './types.js';
+export const chapterRevisionHandler = async (state, content) => {
+    requireNonEmpty(content, 'Chapter revision Markdown');
+    const target = state.pendingAction?.chapterNumber ?? state.currentChapter;
+    const chapterRelative = join('chapters', chapterFileName(target));
+    const versionRelative = join('chapters/.versions', chapterVersionFileName(target, new Date().toISOString()));
+    const archived = await archiveChapterVersion(state.projectPath, chapterRelative, versionRelative);
+    const savedPaths = archived ? [archived] : [];
+    savedPaths.push(await saveMarkdownFile(state.projectPath, chapterRelative, content));
+    await indexChapter(state.projectPath, target, content);
+    return {
+        savedPaths,
+        fileEntries: { [`chapter-${target}`]: chapterRelative },
+        next: { kind: 'sideTrackReturn' },
+    };
+};

package/dist/src/core/steps/continuityReview.js

@@ -0,0 +1,13 @@
+import { ContinuityReviewSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { parseJson } from './types.js';
+export const continuityReviewHandler = async (state, content) => {
+    const parsed = ContinuityReviewSchema.parse(parseJson(content));
+    const relative = `reviews/continuity-${parsed.range.start}-${parsed.range.end}.json`;
+    const path = await saveJsonFile(state.projectPath, relative, parsed);
+    return {
+        savedPaths: [path],
+        fileEntries: { continuityReview: relative },
+        next: { kind: 'linear', nextStep: 'complete' },
+    };
+};

package/dist/src/core/steps/crossChapterReview.js

@@ -0,0 +1,15 @@
+import { join } from 'node:path';
+import { CrossChapterReviewSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { crossChapterReviewFileName } from '../fileNames.js';
+import { parseJson } from './types.js';
+export const crossChapterReviewHandler = async (state, content) => {
+    const parsed = CrossChapterReviewSchema.parse(parseJson(content));
+    const relative = join('reviews/cross', crossChapterReviewFileName(parsed.range.start, parsed.range.end));
+    const path = await saveJsonFile(state.projectPath, relative, parsed);
+    return {
+        savedPaths: [path],
+        fileEntries: { [`review-cross-${parsed.range.start}-${parsed.range.end}`]: relative },
+        next: { kind: 'sideTrackReturn' },
+    };
+};

package/dist/src/core/steps/index.js

@@ -0,0 +1,20 @@
+import { architectureHandler } from './architecture.js';
+import { chapterHandler } from './chapter.js';
+import { chapterReviewHandler } from './chapterReview.js';
+import { chapterRevisionHandler } from './chapterRevision.js';
+import { continuityReviewHandler } from './continuityReview.js';
+import { crossChapterReviewHandler } from './crossChapterReview.js';
+import { memoryCardHandler } from './memoryCard.js';
+import { novelMetadataHandler } from './novelMetadata.js';
+import { storyBibleHandler } from './storyBible.js';
+export const STEP_HANDLERS = {
+    novel_metadata: novelMetadataHandler,
+    story_bible: storyBibleHandler,
+    architecture: architectureHandler,
+    chapter: chapterHandler,
+    memory_card: memoryCardHandler,
+    continuity_review: continuityReviewHandler,
+    chapter_review: chapterReviewHandler,
+    chapter_revision: chapterRevisionHandler,
+    cross_chapter_review: crossChapterReviewHandler,
+};

package/dist/src/core/steps/memoryCard.js

@@ -0,0 +1,22 @@
+import { join } from 'node:path';
+import { MemoryCardSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { memoryFileName } from '../fileNames.js';
+import { indexMemoryCard } from '../retrieval/index.js';
+import { parseJson } from './types.js';
+export const memoryCardHandler = async (state, content) => {
+    const parsed = MemoryCardSchema.parse(parseJson(content));
+    const relative = join('memory', memoryFileName(state.currentChapter));
+    const path = await saveJsonFile(state.projectPath, relative, parsed);
+    await indexMemoryCard(state.projectPath, state.currentChapter, parsed);
+    const nextChapter = state.currentChapter + 1;
+    return {
+        savedPaths: [path],
+        fileEntries: { [`memory-${state.currentChapter}`]: relative },
+        next: {
+            kind: 'linear',
+            nextStep: nextChapter > state.targetChapters ? 'continuity_review' : 'chapter',
+            statePatch: { currentChapter: nextChapter },
+        },
+    };
+};

package/dist/src/core/steps/novelMetadata.js

@@ -0,0 +1,12 @@
+import { NovelMetadataSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { parseJson } from './types.js';
+export const novelMetadataHandler = async (state, content) => {
+    const parsed = NovelMetadataSchema.parse(parseJson(content));
+    const path = await saveJsonFile(state.projectPath, 'novel.json', parsed);
+    return {
+        savedPaths: [path],
+        fileEntries: { novel: 'novel.json' },
+        next: { kind: 'linear', nextStep: 'story_bible' },
+    };
+};

package/dist/src/core/steps/storyBible.js

@@ -0,0 +1,13 @@
+import { saveMarkdownFile } from '../projectStore.js';
+import { indexStoryBible } from '../retrieval/index.js';
+import { requireNonEmpty } from './types.js';
+export const storyBibleHandler = async (state, content) => {
+    requireNonEmpty(content, 'Story bible Markdown');
+    const path = await saveMarkdownFile(state.projectPath, 'story-bible.md', content);
+    await indexStoryBible(state.projectPath, content);
+    return {
+        savedPaths: [path],
+        fileEntries: { storyBible: 'story-bible.md' },
+        next: { kind: 'linear', nextStep: 'architecture' },
+    };
+};

package/dist/src/core/steps/types.js

@@ -0,0 +1,7 @@
+export function parseJson(content) {
+    return JSON.parse(content);
+}
+export function requireNonEmpty(content, label) {
+    if (!content.trim())
+        throw new Error(`${label} is empty`);
+}

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/workflow.js

@@ -0,0 +1,186 @@
+import { readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildContext } from './contextBuilder.js';
+import { buildPromptForStep } from './prompts.js';
+import { loadState, saveJsonFile, saveRecoveryFile, saveState } from './projectStore.js';
+import { STEP_HANDLERS } from './steps/index.js';
+const CONTEXT_RECIPES = {
+    chapter: (s) => ({ purpose: 'chapter_generation', chapterNumber: s.currentChapter }),
+    memory_card: (s) => ({ purpose: 'memory_extraction', chapterNumber: s.currentChapter }),
+    continuity_review: () => ({ purpose: 'continuity_review' }),
+    chapter_review: (s) => ({
+        purpose: 'chapter_review',
+        chapterNumber: s.pendingAction?.chapterNumber ?? s.currentChapter,
+    }),
+    chapter_revision: (s) => ({
+        purpose: 'revision',
+        chapterNumber: s.pendingAction?.chapterNumber ?? s.currentChapter,
+        feedback: s.pendingAction?.feedback,
+    }),
+    cross_chapter_review: (s) => ({
+        purpose: 'cross_chapter_review',
+        range: s.pendingAction?.range,
+    }),
+};
+async function contextForStep(state) {
+    const recipe = CONTEXT_RECIPES[state.currentStep];
+    if (!recipe)
+        return '';
+    return buildContext({ projectPath: state.projectPath, ...recipe(state) });
+}
+async function instructionFor(state) {
+    const base = {
+        projectId: state.projectId,
+        projectPath: state.projectPath,
+        currentStep: state.currentStep,
+    };
+    if (state.currentStep === 'complete') {
+        return { ...base, instruction: 'The workflow is complete.', expectedFormat: 'No output required', context: '' };
+    }
+    const context = await contextForStep(state);
+    const prompt = buildPromptForStep({ state, context });
+    return { ...base, instruction: prompt.prompt, expectedFormat: prompt.expectedFormat, context };
+}
+export async function getNextStep(projectPath) {
+    return instructionFor(await loadState(projectPath));
+}
+const SIDE_TRACK_FILE = '.agent-recovery/side-track.json';
+async function saveSideTrack(state, entry) {
+    await saveState(state);
+    await saveJsonFile(state.projectPath, SIDE_TRACK_FILE, entry);
+}
+async function loadSideTrack(projectPath) {
+    try {
+        const raw = await readFile(join(projectPath, SIDE_TRACK_FILE), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function clearSideTrack(projectPath) {
+    try {
+        await unlink(join(projectPath, SIDE_TRACK_FILE));
+    }
+    catch {
+        // ignore: nothing to clear
+    }
+}
+function maxExistingChapter(state) {
+    let max = 0;
+    for (const key of Object.keys(state.files)) {
+        const match = key.match(/^chapter-(\d+)$/);
+        if (match) {
+            const num = Number(match[1]);
+            if (num > max)
+                max = num;
+        }
+    }
+    return max;
+}
+function buildPendingAction(state, input) {
+    switch (input.step) {
+        case 'chapter_review': {
+            if (!input.chapterNumber)
+                throw new Error('chapter_review requires chapterNumber');
+            return { step: 'chapter_review', chapterNumber: input.chapterNumber };
+        }
+        case 'chapter_revision': {
+            if (!input.chapterNumber)
+                throw new Error('chapter_revision requires chapterNumber');
+            return { step: 'chapter_revision', chapterNumber: input.chapterNumber, feedback: input.feedback };
+        }
+        case 'cross_chapter_review': {
+            const max = maxExistingChapter(state);
+            const range = input.range ?? { start: 1, end: max || state.currentChapter };
+            if (range.start < 1 || range.end < range.start)
+                throw new Error('Invalid range');
+            return { step: 'cross_chapter_review', range };
+        }
+        default:
+            throw new Error(`Unknown side-track step: ${input.step}`);
+    }
+}
+export async function requestSideTrack(input) {
+    const state = await loadState(input.projectPath);
+    const pendingAction = buildPendingAction(state, input);
+    const next = { ...state, currentStep: input.step, pendingAction };
+    await saveSideTrack(next, {
+        step: input.step,
+        resumeStep: state.currentStep,
+        resumeChapter: state.currentChapter,
+        pendingAction,
+    });
+    return instructionFor(next);
+}
+// =============================================================================
+// Submit dispatcher — thin glue over STEP_HANDLERS
+// =============================================================================
+function advanceLinear(state, nextStep, fileEntries = {}, statePatch = {}) {
+    const { pendingAction: _pending, ...rest } = state;
+    return {
+        ...rest,
+        ...statePatch,
+        currentStep: nextStep,
+        completedSteps: [...state.completedSteps, state.currentStep],
+        files: { ...state.files, ...fileEntries },
+    };
+}
+async function resumeFromSideTrack(state, fileEntries) {
+    const sideTrack = await loadSideTrack(state.projectPath);
+    await clearSideTrack(state.projectPath);
+    return {
+        ...state,
+        currentStep: sideTrack?.resumeStep ?? state.currentStep,
+        currentChapter: sideTrack?.resumeChapter ?? state.currentChapter,
+        completedSteps: [...state.completedSteps, state.currentStep],
+        files: { ...state.files, ...fileEntries },
+        pendingAction: undefined,
+    };
+}
+export async function submitStepResult(input) {
+    const state = await loadState(input.projectPath);
+    if (state.currentStep !== input.step) {
+        const recoveryPath = await saveRecoveryFile(state.projectPath, input.step, input.content);
+        return {
+            validation: { ok: false, message: `Expected step ${state.currentStep}, got ${input.step}` },
+            state,
+            savedPaths: [],
+            recoveryPath,
+            next: await instructionFor(state),
+        };
+    }
+    const handler = STEP_HANDLERS[input.step];
+    if (!handler) {
+        return {
+            validation: { ok: false, message: `Step ${input.step} accepts no submission` },
+            state,
+            savedPaths: [],
+            next: await instructionFor(state),
+        };
+    }
+    try {
+        const result = await handler(state, input.content);
+        const fileEntries = result.fileEntries ?? {};
+        const nextState = result.next.kind === 'linear'
+            ? advanceLinear(state, result.next.nextStep, fileEntries, result.next.statePatch)
+            : await resumeFromSideTrack(state, fileEntries);
+        await saveState(nextState);
+        return {
+            validation: { ok: true, message: 'Saved' },
+            state: nextState,
+            savedPaths: result.savedPaths,
+            next: await instructionFor(nextState),
+        };
+    }
+    catch (error) {
+        const recoveryPath = await saveRecoveryFile(state.projectPath, input.step, input.content);
+        return {
+            validation: { ok: false, message: error.message },
+            state,
+            savedPaths: [],
+            recoveryPath,
+            next: await instructionFor(state),
+        };
+    }
+}

package/dist/src/mcp/server.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createNovelAgentServer } from './tools.js';
+async function main() {
+    const workspaceRoot = process.env.NOVELFORGE_WORKSPACE || process.cwd();
+    const server = createNovelAgentServer({ workspaceRoot });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+});

package/dist/src/mcp/tools.js

@@ -0,0 +1,126 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { buildContext, chapterFileName, createProject, getNextStep, getProjectStatus, listProjects, requestSideTrack, retrieve, saveMarkdownFile, submitStepResult, } from '../core/index.js';
+function textResult(value) {
+    return {
+        content: [{
+                type: 'text',
+                text: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+            }],
+    };
+}
+export function createNovelAgentServer(options) {
+    const server = new McpServer({
+        name: 'novelforge-agent',
+        version: '0.1.0',
+    });
+    server.tool('start_novel_project', 'Create a local novel project and return the first generation instruction.', {
+        prompt: z.string().min(1),
+        language: z.enum(['zh-CN', 'en-US']).default('zh-CN'),
+        outputDir: z.string().default('novels'),
+        targetChapters: z.number().int().positive().default(3),
+    }, async ({ prompt, language, outputDir, targetChapters }) => {
+        const result = await createProject({
+            workspaceRoot: options.workspaceRoot,
+            prompt,
+            language,
+            outputDir,
+            targetChapters,
+        });
+        return textResult({ state: result.state, next: await getNextStep(result.state.projectPath) });
+    });
+    server.tool('list_projects', 'List all NovelForge projects under the workspace, sorted by most recently updated. Use this to find an existing projectPath instead of asking the user.', {
+        outputDir: z.string().default('novels'),
+    }, async ({ outputDir }) => textResult(await listProjects({ workspaceRoot: options.workspaceRoot, outputDir })));
+    server.tool('get_project_status', 'Return a compact, one-screen summary of a project: current step, chapters written, open threads, latest review verdict, completion state.', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult(await getProjectStatus(projectPath)));
+    server.tool('get_next_step', 'Return the next required generation step for a novel project.', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult(await getNextStep(projectPath)));
+    server.tool('submit_step_result', 'Submit host-generated content for validation, saving, and workflow advancement.', {
+        projectPath: z.string().min(1),
+        step: z.enum([
+            'novel_metadata',
+            'story_bible',
+            'architecture',
+            'chapter',
+            'memory_card',
+            'continuity_review',
+            'chapter_review',
+            'chapter_revision',
+            'cross_chapter_review',
+            'complete',
+        ]),
+        content: z.string(),
+    }, async ({ projectPath, step, content }) => textResult(await submitStepResult({ projectPath, step, content })));
+    server.tool('get_context', 'Build purpose-specific context for generation, memory extraction, review, or revision.', {
+        projectPath: z.string().min(1),
+        purpose: z.enum([
+            'chapter_generation',
+            'memory_extraction',
+            'continuity_review',
+            'revision',
+            'chapter_review',
+            'cross_chapter_review',
+        ]),
+        chapterNumber: z.number().int().positive().optional(),
+        start: z.number().int().positive().optional(),
+        end: z.number().int().positive().optional(),
+    }, async ({ projectPath, purpose, chapterNumber, start, end }) => textResult(await buildContext({
+        projectPath,
+        purpose,
+        chapterNumber,
+        range: start && end ? { start, end } : undefined,
+    })));
+    server.tool('save_chapter', 'Save a generated chapter directly as Markdown.', {
+        projectPath: z.string().min(1),
+        chapterNumber: z.number().int().positive(),
+        title: z.string().min(1),
+        content: z.string().min(1),
+    }, async ({ projectPath, chapterNumber, title, content }) => {
+        const fileName = `chapters/${chapterFileName(chapterNumber)}`;
+        const savedPath = await saveMarkdownFile(projectPath, fileName, `# ${title}\n\n${content}`);
+        return textResult({ savedPath, suggestedNextStep: 'memory_card' });
+    });
+    server.tool('generate_chapter', 'Build the chapter-generation context and instruction for a specific chapter without changing workflow state.', {
+        projectPath: z.string().min(1),
+        chapterNumber: z.number().int().positive(),
+    }, async ({ projectPath, chapterNumber }) => textResult({
+        context: await buildContext({ projectPath, purpose: 'chapter_generation', chapterNumber }),
+        hint: 'Persist the result via save_chapter or submit_step_result(step="chapter") when the workflow currentStep is "chapter".',
+    }));
+    server.tool('extract_memory_card', 'Build the memory-extraction context for a specific chapter without changing workflow state.', {
+        projectPath: z.string().min(1),
+        chapterNumber: z.number().int().positive(),
+    }, async ({ projectPath, chapterNumber }) => textResult({
+        context: await buildContext({ projectPath, purpose: 'memory_extraction', chapterNumber }),
+        hint: 'Submit the extracted memory card via submit_step_result with step="memory_card" when the workflow currentStep matches.',
+    }));
+    server.tool('review_chapter', 'Ask the host to review a specific chapter. Switches the workflow into chapter_review side-track and returns the review prompt + packed context. Resume original step after submit_step_result(step="chapter_review").', {
+        projectPath: z.string().min(1),
+        chapterNumber: z.number().int().positive(),
+    }, async ({ projectPath, chapterNumber }) => textResult(await requestSideTrack({ projectPath, step: 'chapter_review', chapterNumber })));
+    server.tool('revise_chapter', 'Ask the host to rewrite a specific chapter based on prior review feedback and optional extra instructions. Previous version is archived under chapters/.versions/.', {
+        projectPath: z.string().min(1),
+        chapterNumber: z.number().int().positive(),
+        feedback: z.string().optional(),
+    }, async ({ projectPath, chapterNumber, feedback }) => textResult(await requestSideTrack({ projectPath, step: 'chapter_revision', chapterNumber, feedback })));
+    server.tool('retrieve', 'Lexical BM25-style retrieval over indexed chapter paragraphs, story-bible sections, and memory cards. Returns ranked snippets with chapter attribution.', {
+        projectPath: z.string().min(1),
+        query: z.string().min(1),
+        topK: z.number().int().positive().max(50).default(6),
+        types: z.array(z.enum(['chapter', 'bible', 'memory'])).optional(),
+        chapterStart: z.number().int().positive().optional(),
+        chapterEnd: z.number().int().positive().optional(),
+    }, async ({ projectPath, query, topK, types, chapterStart, chapterEnd }) => {
+        const chapterRange = chapterStart && chapterEnd ? { start: chapterStart, end: chapterEnd } : undefined;
+        const hits = await retrieve(projectPath, query, { topK, types, chapterRange });
+        return textResult({ query, hits });
+    });
+    server.tool('cross_chapter_review', 'Ask the host to review a chapter range for cross-chapter continuity conflicts. Defaults to all generated chapters.', {
+        projectPath: z.string().min(1),
+        start: z.number().int().positive().optional(),
+        end: z.number().int().positive().optional(),
+    }, async ({ projectPath, start, end }) => {
+        const range = start && end ? { start, end } : undefined;
+        return textResult(await requestSideTrack({ projectPath, step: 'cross_chapter_review', range }));
+    });
+    return server;
+}