dsh-openwrite 0.2.8

package/packages/openwrite-bridge/lib/tools.js

@@ -0,0 +1,2404 @@
+/**
+ * The `novel_*` tool definitions bridging dsh agents to the OpenWrite Studio
+ * HTTP action surface. Payload shapes are verified against OpenWrite
+ * `tools/studio_http.py` (POST_ROUTES / do_GET / do_PUT) and
+ * `tools/studio_application.py` (the dispatched methods).
+ */
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { StudioError } from './client.js';
+import { materializeChapterDelivery } from './dog-delivery.js';
+import { materializeCompletedDogTaskReview, materializeDogReview, reviewChapterId } from './dog-review.js';
+/** Render an arbitrary JSON payload as pretty-printed model-facing text. */
+function renderJson(value) {
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+/** The schema for tools whose canonical value is an opaque Studio JSON payload. */
+const JSON_OUTPUT_SCHEMA = {
+    type: 'json',
+    description: 'The JSON payload returned by the OpenWrite Studio API.',
+};
+/** Manuscript chapter ids accepted by OpenWrite (`ch_<digits>`). */
+const CHAPTER_ID_PATTERN = /^ch_\d+$/;
+/** Resolve a review target: an explicit manuscript path, or a chapter id mapped to `data/manuscript/<id>.md`. */
+function resolveReviewPath(args) {
+    const path = args.path?.trim();
+    if (path)
+        return path;
+    const chapterId = args.chapter_id?.trim();
+    if (!chapterId)
+        throw new Error('either path or chapter_id is required');
+    if (!CHAPTER_ID_PATTERN.test(chapterId))
+        throw new Error(`chapter_id must match ch_<digits>, got "${chapterId}"`);
+    return `data/manuscript/${chapterId}.md`;
+}
+function objectValue(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+async function deliveryForResponse(client, response, chapterId, signal, threshold) {
+    const embedded = objectValue(response)['workspace'];
+    const workspace = embedded !== null && typeof embedded === 'object' && !Array.isArray(embedded)
+        ? embedded
+        : await client.getJson('/api/workspace', {}, signal);
+    return await materializeChapterDelivery(workspace, chapterId, threshold, client.context?.workspaceRoot);
+}
+/**
+ * Derive the request-scoped Workspace context from the tool execution, failing
+ * closed (docs/WORKSPACE_CONTEXT_CONTRACT.md §2.1): the stamped session cwd is
+ * the only root source — never a fallback to the plugin cwd or a fixed project.
+ */
+export function workspaceContextFromExec(exec) {
+    const header = exec.agent?.session?.header;
+    const cwd = header?.cwd;
+    if (cwd === undefined || cwd.trim() === '') {
+        throw new StudioError('novel_* tool call lacks a Workspace context: exec.agent.session.header.cwd is missing', 400, 'WORKSPACE_CONTEXT_MISSING');
+    }
+    if (!isAbsolute(cwd)) {
+        throw new StudioError(`Workspace root is not an absolute path: ${cwd}`, 400, 'WORKSPACE_ROOT_INVALID', { reason: 'not_absolute' });
+    }
+    let workspaceRoot;
+    try {
+        workspaceRoot = realpathSync(cwd);
+    }
+    catch {
+        throw new StudioError(`Workspace root cannot be canonicalized: ${cwd}`, 400, 'WORKSPACE_ROOT_INVALID', { reason: 'not_found' });
+    }
+    return {
+        workspaceRoot,
+        sessionId: header?.id,
+        toolCallId: String(exec.callId),
+        rootCallId: String(exec.rootCallId ?? exec.callId),
+        toolName: exec.name,
+    };
+}
+/** Per-root export directory: `<outputDir>/<sha256(workspaceRoot)[:12]>`. */
+function outputDirFor(outputDir, client) {
+    const workspaceRoot = client.context?.workspaceRoot;
+    // Unreachable in practice: clientFor fails closed before any handler runs.
+    if (workspaceRoot === undefined)
+        return outputDir;
+    return join(outputDir, createHash('sha256').update(workspaceRoot).digest('hex').slice(0, 12));
+}
+/** A server-supplied download name is a filename, never a relative path. */
+function exportFilename(filename, fallback) {
+    const name = filename === 'export.bin' ? fallback : filename;
+    // Check both platforms' separators, drive prefixes and control characters
+    // before joining: exports may later be moved between macOS and Windows.
+    if (name.trim() === '' || name === '.' || name === '..' || /[\\/\u0000-\u001f\u007f]/.test(name) || /^[A-Za-z]:/.test(name)) {
+        throw new StudioError('Studio returned an unsafe export filename', 502, 'INVALID_EXPORT_FILENAME', { reason: 'not_basename' });
+    }
+    return name;
+}
+/** Register every `novel_*` tool into the host tools registry. */
+export function registerNovelTools(ctx, clientFactory, options) {
+    const { timeoutMs, outputDir } = options;
+    // Every handler resolves its own request-scoped client from the execution;
+    // a missing/invalid Workspace context fails closed before any HTTP call.
+    const clientFor = (exec) => clientFactory(exec);
+    // ── reads ──────────────────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_embedding_profiles',
+        description: 'List independent Embedding profiles and the active selection. Embedding is configured separately from Chat profiles.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return await clientFor(exec).getJson('/api/model/embedding', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_embedding_profile_save',
+        description: 'Create or update an independent Embedding profile; it is never attached to a Chat profile.',
+        parameters: {
+            profile: { type: 'json', required: true, description: 'Embedding profile: id, label, provider, model, base_url, dimension, max_tokens.' },
+            api_key: { type: 'string', description: 'Embedding API key.' },
+            remember_api_key: { type: 'boolean', description: 'Persist the key (default true).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (typeof args.profile !== 'object' || args.profile === null || Array.isArray(args.profile))
+                throw new Error('profile must be a JSON object');
+            const body = { ...args.profile };
+            for (const key of ['api_key', 'remember_api_key'])
+                if (args[key] !== undefined)
+                    body[key] = args[key];
+            return await clientFor(exec).postJson('/api/model/embedding', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_embedding_profile_select',
+        description: 'Select the active independent Embedding profile used by search.',
+        parameters: { profile_id: { type: 'string', required: true } },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.profile_id.trim())
+                throw new Error('profile_id must be non-empty');
+            return await clientFor(exec).postJson('/api/model/embedding/select', { profile_id: args.profile_id }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_embedding_profile_delete',
+        description: 'Delete an independent Embedding profile; the active profile automatically moves to another one.',
+        parameters: { profile_id: { type: 'string', required: true } },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.profile_id.trim())
+                throw new Error('profile_id must be non-empty');
+            return await clientFor(exec).postJson('/api/model/embedding/delete', { profile_id: args.profile_id }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_status',
+        description: 'Get a snapshot of the current OpenWrite novel project: title, chapters, word counts, writing targets, and focus compass.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/workspace', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_review_framework',
+        description: 'Inspect the canonical reusable chapter-review DAG blueprint: its version, revision, six quality domains, 37 checks, hard gates, dependencies, invariants, and extension points.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return await clientFor(exec).getJson('/api/review/framework', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_manuscript_acceptance',
+        description: 'Inspect the canonical manuscript acceptance ledger: current and accepted content revisions, drift, ' +
+            'recoverable operations, derived-result impacts, and chapters that require author review.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return await clientFor(exec).getJson('/api/manuscript/acceptance', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_trace_list',
+        description: 'Inspect recent redacted Prompt→context→model→tool→domain traces. Raw prompts, context, model output, credentials, chain-of-thought, and mutation values are never stored.',
+        parameters: {
+            limit: { type: 'number', description: 'Maximum records to return (1-100, default 20).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const limit = Math.max(1, Math.min(100, Math.trunc(args.limit ?? 20)));
+            return await clientFor(exec).getJson('/api/traces', { limit: String(limit) }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_context_preview',
+        description: 'Preview the context packet OpenWrite would assemble for writing a chapter (relevant outline, assets, foreshadowing, and prior-chapter memory).',
+        parameters: {
+            chapter: { type: 'string', description: 'Chapter id (e.g. "ch_0007"); omit or pass "next" for the next chapter to write.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/context', { chapter: args.chapter?.trim() || 'next' }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_outline_read',
+        description: 'Read the live outline tree. The response carries a `revision` fingerprint required by novel_outline_edit and a chapter `recommendation`.',
+        parameters: {
+            chapter: { type: 'string', description: 'Optional chapter id to get a writing recommendation for.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const params = {};
+            const chapter = args.chapter?.trim();
+            if (chapter)
+                params['chapter'] = chapter;
+            return await client.getJson('/api/outline', params, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_reading_order',
+        description: 'Read the canonical manuscript order with stable document/occurrence ids, volume membership, previous/next links, revision, and explicit duplicate or missing-file issues.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return await clientFor(exec).getJson('/api/reading-order', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_reading_packet',
+        description: 'Read a bounded continuous-reading window around one stable manuscript document or occurrence id.',
+        parameters: {
+            document_id: { type: 'string', required: true, description: 'Stable document_id or occurrence_id from novel_reading_order.' },
+            before: { type: 'integer', description: 'Number of preceding chapters (0-20, default 1).' },
+            after: { type: 'integer', description: 'Number of following chapters (0-20, default 1).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            if (!args.document_id.trim())
+                throw new Error('document_id must be non-empty');
+            const params = { document_id: args.document_id };
+            if (args.before !== undefined)
+                params['before'] = String(args.before);
+            if (args.after !== undefined)
+                params['after'] = String(args.after);
+            return await clientFor(exec).getJson('/api/reading-packet', params, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_chapter_work',
+        description: 'Read one chapter work brief: manuscript/acceptance/review revisions, writing target, recent edits, tasks, and categorized foreshadowing obligations.',
+        parameters: {
+            chapter_id: { type: 'string', required: true, description: 'Chapter id (ch_<digits>).' },
+            document_id: { type: 'string', description: 'Stable document id used to bind recent activity.' },
+            recent_limit: { type: 'integer', description: 'Maximum recent edit records (default 20).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            if (!CHAPTER_ID_PATTERN.test(args.chapter_id))
+                throw new Error(`chapter_id must match ch_<digits>, got "${args.chapter_id}"`);
+            const params = {};
+            if (args.document_id !== undefined)
+                params['document_id'] = args.document_id;
+            if (args.recent_limit !== undefined)
+                params['recent_limit'] = String(args.recent_limit);
+            return await clientFor(exec).getJson(`/api/chapters/${encodeURIComponent(args.chapter_id)}/work-brief`, params, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_scene_structure',
+        description: 'Read the canonical scene structure with stable scene ids, reading/story-time order, chapter revisions, references, freshness, and explicit issues.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return await clientFor(exec).getJson('/api/scenes', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_chapter_scenes',
+        description: 'Read the revision-labelled scene slice for one chapter.',
+        parameters: {
+            chapter_id: { type: 'string', required: true, description: 'Chapter id (ch_<digits>).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            if (!CHAPTER_ID_PATTERN.test(args.chapter_id))
+                throw new Error(`chapter_id must match ch_<digits>, got "${args.chapter_id}"`);
+            return await clientFor(exec).getJson(`/api/chapters/${encodeURIComponent(args.chapter_id)}/scenes`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_scene_migration_preview',
+        description: 'Build a read-only, exact-revision preview that segments existing chapters into stable scenes. This does not write a sidecar.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return await clientFor(exec).getJson('/api/scenes/migration-preview', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_assets_list',
+        description: 'List structured assets (characters, world entities, progression systems) of the current novel project.',
+        parameters: {
+            kind: { type: 'string', enum: ['character', 'world', 'progression'], description: 'Restrict to one asset kind; omit to list all kinds.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/assets', { kind: args.kind ?? '' }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_search',
+        description: 'Search the novel project (semantic + exact match) across chapters, outline, and assets.',
+        parameters: {
+            q: { type: 'string', required: true, description: 'The search query.' },
+            scope: { type: 'string', description: 'Search scope, e.g. "all" (default), "chapters", "outline", "assets".' },
+            limit: { type: 'integer', description: 'Maximum number of results (server default 20).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.q.trim())
+                throw new Error('q must be a non-empty string');
+            const params = { q: args.q };
+            if (args.scope !== undefined)
+                params['scope'] = args.scope;
+            if (args.limit !== undefined)
+                params['limit'] = String(args.limit);
+            return await client.getJson('/api/search', params, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_doc_read',
+        description: 'Read a project document (path relative to the novel data root, e.g. "src/outline.md" or "data/manuscript/ch_0007.md"). Returns content plus a `version` fingerprint needed by novel_doc_write.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'Document path relative to the novel data root.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.path.trim())
+                throw new Error('path must be a non-empty string');
+            return await client.getJson('/api/document', { path: args.path }, exec.signal);
+        },
+    }));
+    // ── writes ─────────────────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_outline_edit',
+        description: 'Immediate compatibility write for an outline change the author has already authorized exactly; otherwise use ' +
+            'novel_structured_change_plan. Apply ONE atomic structural edit to the outline tree. Edits are revision-gated: ' +
+            'read the current `revision` via novel_outline_read first and pass it back; the server ' +
+            'rejects the edit with a conflict if the outline changed in between. ' +
+            'Operations: "rename" (node_id + title), "update_summary" (node_id + summary), ' +
+            '"add_child" (node_id = parent, + title/summary/kind), "add_after" (node_id = sibling, + title/summary/kind), ' +
+            '"delete" (node_id).',
+        parameters: {
+            operation: { type: 'string', required: true, enum: ['rename', 'update_summary', 'add_child', 'add_after', 'delete'], description: 'The structural operation to apply.' },
+            revision: { type: 'string', required: true, description: 'The outline revision fingerprint from a fresh novel_outline_read call.' },
+            node_id: { type: 'string', description: 'Target node id (parent for add_child, sibling for add_after); not needed for add_child at root.' },
+            title: { type: 'string', description: 'Node title (rename / add_child / add_after).' },
+            summary: { type: 'string', description: 'Node summary (update_summary / add_child / add_after).' },
+            kind: { type: 'string', description: 'Node kind, e.g. "volume" or "chapter" (add_child / add_after).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { operation: args.operation, revision: args.revision };
+            if (args.node_id !== undefined)
+                body['node_id'] = args.node_id;
+            if (args.title !== undefined)
+                body['title'] = args.title;
+            if (args.summary !== undefined)
+                body['summary'] = args.summary;
+            if (args.kind !== undefined)
+                body['kind'] = args.kind;
+            return await client.postJson('/api/outline/edit', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_reading_order_move',
+        description: 'Move one manuscript document within or across volumes. Requires the fresh reading-order revision and rejects ambiguous, missing, or concurrently changed order.',
+        parameters: {
+            document_id: { type: 'string', required: true, description: 'Stable document_id or unambiguous occurrence_id.' },
+            target_volume_id: { type: 'string', required: true, description: 'Target volume_id from novel_reading_order.' },
+            target_index: { type: 'integer', required: true, description: 'Zero-based position inside the target volume.' },
+            expected_revision: { type: 'string', required: true, description: 'Fresh reading-order revision used for CAS.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.document_id.trim())
+                throw new Error('document_id must be non-empty');
+            if (!args.target_volume_id.trim())
+                throw new Error('target_volume_id must be non-empty');
+            if (!args.expected_revision.trim())
+                throw new Error('expected_revision must be non-empty');
+            return await clientFor(exec).postJson('/api/reading-order/move', {
+                document_id: args.document_id,
+                target_volume_id: args.target_volume_id,
+                target_index: args.target_index,
+                expected_revision: args.expected_revision,
+            }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_scene_migration_apply',
+        description: 'Apply one freshly read scene migration preview. Requires the exact preview revision and explicit confirmation.',
+        parameters: {
+            expected_preview_revision: { type: 'string', required: true, description: 'Exact preview_revision from novel_scene_migration_preview.' },
+            confirm: { type: 'boolean', required: true, description: 'Must be true after the author approves the preview.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.expected_preview_revision.trim())
+                throw new Error('expected_preview_revision must be non-empty');
+            if (args.confirm !== true)
+                throw new Error('confirm must be true');
+            return await clientFor(exec).postJson('/api/scenes/migration/apply', {
+                expected_preview_revision: args.expected_preview_revision,
+                confirm: true,
+            }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_scene_migration_rollback',
+        description: 'Restore the byte-exact scene sidecar that preceded a migration, guarded by the current scene-structure revision.',
+        parameters: {
+            migration_id: { type: 'string', required: true, description: 'Migration id returned by novel_scene_migration_apply.' },
+            expected_revision: { type: 'string', required: true, description: 'Fresh scene-structure revision used for CAS.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.migration_id.trim() || !args.expected_revision.trim())
+                throw new Error('migration_id and expected_revision must be non-empty');
+            return await clientFor(exec).postJson('/api/scenes/migration/rollback', {
+                migration_id: args.migration_id,
+                expected_revision: args.expected_revision,
+            }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_scene_update',
+        description: 'CAS-update scene title, story time, and character/location/event references without changing manuscript prose.',
+        parameters: {
+            scene_id: { type: 'string', required: true, description: 'Stable scene id from novel_scene_structure.' },
+            expected_revision: { type: 'string', required: true, description: 'Fresh scene-structure revision used for CAS.' },
+            title: { type: 'string', description: 'Optional scene title.' },
+            story_time_sort_key: { type: 'string', description: 'Optional lexical story-time sort key.' },
+            story_time_label: { type: 'string', description: 'Optional author-facing story-time label.' },
+            characters: { type: 'array', items: { type: 'string' }, description: 'Character references; replaces the current list when supplied.' },
+            locations: { type: 'array', items: { type: 'string' }, description: 'Location references; replaces the current list when supplied.' },
+            events: { type: 'array', items: { type: 'string' }, description: 'Event references; replaces the current list when supplied.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.scene_id.trim() || !args.expected_revision.trim())
+                throw new Error('scene_id and expected_revision must be non-empty');
+            const body = { scene_id: args.scene_id, expected_revision: args.expected_revision };
+            if (args.title !== undefined)
+                body['title'] = args.title;
+            if (args.story_time_sort_key !== undefined)
+                body['story_time_sort_key'] = args.story_time_sort_key;
+            if (args.story_time_label !== undefined)
+                body['story_time_label'] = args.story_time_label;
+            if (args.characters !== undefined)
+                body['characters'] = args.characters;
+            if (args.locations !== undefined)
+                body['locations'] = args.locations;
+            if (args.events !== undefined)
+                body['events'] = args.events;
+            return await clientFor(exec).postJson('/api/scenes/metadata', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_scene_move',
+        description: 'Move one complete scene within or across chapters with scene/source/target revision guards. Cross-chapter moves start the existing manuscript acceptance flow.',
+        parameters: {
+            scene_id: { type: 'string', required: true, description: 'Stable scene id from novel_scene_structure.' },
+            target_chapter_id: { type: 'string', required: true, description: 'Target chapter id (ch_<digits>).' },
+            target_index: { type: 'integer', required: true, description: 'Zero-based scene position inside the target chapter.' },
+            expected_revision: { type: 'string', required: true, description: 'Fresh scene-structure revision.' },
+            expected_source_revision: { type: 'string', required: true, description: 'Fresh source chapter revision.' },
+            expected_target_revision: { type: 'string', required: true, description: 'Fresh target chapter revision.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!args.scene_id.trim() || !CHAPTER_ID_PATTERN.test(args.target_chapter_id))
+                throw new Error('scene_id and a valid target_chapter_id are required');
+            if (!args.expected_revision.trim() || !args.expected_source_revision.trim() || !args.expected_target_revision.trim())
+                throw new Error('all scene and chapter revisions are required');
+            return await clientFor(exec).postJson('/api/scenes/move', {
+                scene_id: args.scene_id,
+                target_chapter_id: args.target_chapter_id,
+                target_index: args.target_index,
+                expected_revision: args.expected_revision,
+                expected_source_revision: args.expected_source_revision,
+                expected_target_revision: args.expected_target_revision,
+            }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_write_chapter',
+        description: 'Write a chapter with OpenWrite (LONG-RUNNING, may take several minutes). Omit chapter_id to write ' +
+            'the outline-recommended next chapter; a given chapter_id must match the current recommendation. ' +
+            'Preview context first with novel_context_preview and consult novel_outline_read for the recommendation.',
+        parameters: {
+            target_words: { type: 'integer', description: 'Target word count, 200-12000 (default 3000).' },
+            guidance: { type: 'string', description: 'Writing guidance for this chapter (plot beats, tone, POV notes).' },
+            chapter_id: { type: 'string', description: 'Chapter id to write; must equal the current outline recommendation. Omit for the next chapter.' },
+            temperature: { type: 'number', description: 'Sampling temperature (default 0.7).' },
+            outline_revision: { type: 'string', description: 'Optional outline revision guard from novel_outline_read; the server rejects the write if the outline changed.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const targetWords = args.target_words ?? 3000;
+            if (!Number.isInteger(targetWords) || targetWords < 200 || targetWords > 12000) {
+                throw new Error(`target_words must be an integer between 200 and 12000, got ${String(args.target_words)}`);
+            }
+            const body = { target_words: targetWords, guidance: args.guidance ?? '' };
+            const chapterId = args.chapter_id?.trim();
+            if (chapterId)
+                body['chapter_id'] = chapterId;
+            if (args.temperature !== undefined)
+                body['temperature'] = args.temperature;
+            if (args.outline_revision !== undefined)
+                body['outline_revision'] = args.outline_revision;
+            const response = await client.postJson('/api/write', body, exec.signal);
+            const writeValue = objectValue(response);
+            const writeResult = objectValue(writeValue['result'] ?? response);
+            const writtenChapterId = chapterId || String(writeResult['chapter_id'] ?? '');
+            try {
+                const dogDelivery = await deliveryForResponse(client, response, writtenChapterId, exec.signal);
+                return { ...objectValue(response), dog_delivery: dogDelivery };
+            }
+            catch (error) {
+                return { ...objectValue(response), dog_delivery: { status: 'unavailable', error: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_review_chapter',
+        description: 'Run OpenWrite\'s multi-dimensional review on a drafted manuscript chapter (LONG-RUNNING). ' +
+            'Pass either the manuscript path (e.g. "data/manuscript/ch_0007.md") or a chapter_id like "ch_0007".',
+        parameters: {
+            path: { type: 'string', description: 'Manuscript path relative to the novel data root. Takes precedence over chapter_id.' },
+            chapter_id: { type: 'string', description: 'Chapter id (ch_<digits>), resolved client-side to data/manuscript/<id>.md.' },
+            strict: { type: 'boolean', description: 'Enable strict review mode (default false).' },
+            dimensions: { type: 'array', items: { type: 'integer' }, description: 'Optional list of review dimension numbers (1-37) to restrict to.' },
+            dog_threshold: { type: 'integer', description: 'DoG aggregate score threshold (default 70); this does not change OpenWrite review.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (args.dimensions !== undefined && args.dimensions.some(value => !Number.isInteger(value) || value < 1 || value > 37)) {
+                throw new Error('dimensions must contain only integers from 1 to 37');
+            }
+            const dogThreshold = args.dog_threshold ?? 70;
+            if (!Number.isInteger(dogThreshold) || dogThreshold < 0 || dogThreshold > 100) {
+                throw new Error(`dog_threshold must be an integer between 0 and 100, got ${String(args.dog_threshold)}`);
+            }
+            const body = { path: resolveReviewPath(args) };
+            if (args.strict !== undefined)
+                body['strict'] = args.strict;
+            if (args.dimensions !== undefined)
+                body['dimensions'] = args.dimensions;
+            const response = await client.postJson('/api/review', body, exec.signal);
+            const value = response !== null && typeof response === 'object' && !Array.isArray(response)
+                ? response
+                : { result: response };
+            let dogReview;
+            try {
+                dogReview = await materializeDogReview(response, reviewChapterId(args), dogThreshold, client.context?.workspaceRoot);
+            }
+            catch (error) {
+                dogReview = { status: 'unavailable', error: error instanceof Error ? error.message : String(error) };
+            }
+            let dogDelivery;
+            try {
+                dogDelivery = await deliveryForResponse(client, response, reviewChapterId(args), exec.signal, dogThreshold);
+            }
+            catch (error) {
+                dogDelivery = { status: 'unavailable', error: error instanceof Error ? error.message : String(error) };
+            }
+            return { ...value, dog_review: dogReview, dog_delivery: dogDelivery };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_asset_update',
+        description: 'Immediate compatibility write for an asset change the author has already authorized exactly; otherwise use ' +
+            'novel_structured_change_plan. Update a structured asset (character / world / progression). Revision-gated: pass the `revision` ' +
+            'fingerprint from novel_assets_list; the server rejects the update with a conflict if the asset changed. ' +
+            'Pass field changes via `data` (merged into the asset front matter), `body_markdown` to replace the ' +
+            'markdown body, or `raw_text` to replace the whole document.',
+        parameters: {
+            kind: { type: 'string', required: true, enum: ['character', 'world', 'progression'], description: 'Asset kind.' },
+            id: { type: 'string', required: true, description: 'Asset id.' },
+            revision: { type: 'string', required: true, description: 'The asset revision fingerprint from a fresh novel_assets_list call.' },
+            data: { type: 'json', description: 'Object of asset fields to merge (e.g. name, summary, aliases).' },
+            body_markdown: { type: 'string', description: 'Replacement markdown body (character/world assets).' },
+            raw_text: { type: 'string', description: 'Full replacement document text, validated by the server.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { kind: args.kind, id: args.id, revision: args.revision };
+            if (args.data !== undefined)
+                body['data'] = args.data;
+            if (args.body_markdown !== undefined)
+                body['body_markdown'] = args.body_markdown;
+            if (args.raw_text !== undefined)
+                body['raw_text'] = args.raw_text;
+            return await client.postJson('/api/assets/update', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_foreshadowing',
+        description: 'Immediate compatibility write for a foreshadowing change the author has already authorized exactly; otherwise use ' +
+            'novel_structured_change_plan. Manage the foreshadowing DAG. action "create": node_id + content, optional weight (1-10, default 5), ' +
+            'layer (default "支线"), target_chapter. action "update": node_id + status (e.g. planted/paid-off).',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['create', 'update'], description: 'Create a new foreshadowing node or update an existing one.' },
+            node_id: { type: 'string', required: true, description: 'Foreshadowing node id.' },
+            content: { type: 'string', description: 'Node content (create).' },
+            weight: { type: 'integer', description: 'Narrative weight 1-10 (create, default 5).' },
+            layer: { type: 'string', description: 'Story layer, e.g. "主线" or "支线" (create, default "支线").' },
+            target_chapter: { type: 'string', description: 'Chapter id the foreshadowing should pay off at (create).' },
+            status: { type: 'string', description: 'New node status (update).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.node_id.trim())
+                throw new Error('node_id must be a non-empty string');
+            const body = { action: args.action, node_id: args.node_id };
+            if (args.content !== undefined)
+                body['content'] = args.content;
+            if (args.weight !== undefined)
+                body['weight'] = args.weight;
+            if (args.layer !== undefined)
+                body['layer'] = args.layer;
+            if (args.target_chapter !== undefined)
+                body['target_chapter'] = args.target_chapter;
+            if (args.status !== undefined)
+                body['status'] = args.status;
+            return await client.postJson('/api/foreshadowing', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_doc_write',
+        description: 'Write a project document (path relative to the novel data root). Uses a version-based optimistic lock: ' +
+            'pass the `version` returned by novel_doc_read; the server rejects with a conflict if the document changed. ' +
+            'Omit version to create a new document; set force to bypass the lock.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'Document path relative to the novel data root.' },
+            content: { type: 'string', required: true, description: 'Full new document content (max 2 MB).' },
+            version: { type: 'string', description: 'The version fingerprint from novel_doc_read (optimistic lock).' },
+            force: { type: 'boolean', description: 'Bypass the version check (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.path.trim())
+                throw new Error('path must be a non-empty string');
+            const body = { path: args.path, content: args.content };
+            if (args.version !== undefined)
+                body['version'] = args.version;
+            if (args.force !== undefined)
+                body['force'] = args.force;
+            return await client.putJson('/api/document', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_document_change_plan',
+        description: 'Stage and review revision-gated changes to an existing novel document. Use action "preview" with path and edits ' +
+            'to receive an immutable preview_token and real before/after summary. Use "apply" only after author acceptance, ' +
+            'passing only that token; "reject" discards it, "retry" rebuilds it against the current source, and "undo" safely ' +
+            'applies an undo_preview_token returned by a prior apply. Each edit uses old_text/new_text or unique start_text/' +
+            'end_text/new_text anchors. The server rechecks the source revision and writes exactly the stored preview.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['preview', 'apply', 'reject', 'retry', 'undo'], description: 'Plan lifecycle action.' },
+            path: { type: 'string', description: 'Existing document path for preview, relative to the novel root.' },
+            edits: { type: 'json', description: 'Preview edits: [{old_text,new_text}] or [{start_text,end_text,new_text}].' },
+            preview_token: { type: 'string', description: 'Immutable preview or undo token for apply/reject/retry/undo.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (args.action === 'preview' && (!Array.isArray(args.edits) || args.edits.length !== 1)) {
+                throw new Error('preview requires exactly one edit so the author can accept or reject each change independently');
+            }
+            if (args.action !== 'preview' && !args.preview_token?.trim()) {
+                throw new Error(`${args.action} requires preview_token`);
+            }
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            if (args.path !== undefined)
+                body['path'] = args.path;
+            if (args.edits !== undefined)
+                body['edits'] = args.edits;
+            if (args.preview_token !== undefined)
+                body['preview_token'] = args.preview_token;
+            return await client.postJson('/api/document/change-plan', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_structured_change_plan',
+        description: 'Stage one structured OpenWrite domain change without writing it. Supported change_kind values are "outline", ' +
+            '"asset", "focus", "foreshadowing", and "writing_targets"; `change` uses the corresponding direct tool payload. ' +
+            'Use action "preview" to receive an immutable token and entity-level before/after summary. Only after author ' +
+            'acceptance pass that token unchanged to "apply". "reject" consumes it, "retry" rebuilds the same semantic ' +
+            'change against current source, and "undo" accepts only the revision-bound undo token returned by apply. The ' +
+            'server writes the exact validated preview and rejects source conflicts.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['preview', 'apply', 'reject', 'retry', 'undo'], description: 'Plan lifecycle action.' },
+            change_kind: { type: 'string', enum: ['outline', 'asset', 'focus', 'foreshadowing', 'writing_targets'], description: 'Structured domain for a preview.' },
+            change: { type: 'json', description: 'One direct-tool-shaped change object, required for preview.' },
+            preview_token: { type: 'string', description: 'Immutable preview or undo token for apply/reject/retry/undo.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (args.action === 'preview') {
+                if (!args.change_kind)
+                    throw new Error('preview requires change_kind');
+                if (args.change === null || typeof args.change !== 'object' || Array.isArray(args.change)) {
+                    throw new Error('preview requires one change object');
+                }
+            }
+            else if (!args.preview_token?.trim()) {
+                throw new Error(`${args.action} requires preview_token`);
+            }
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            if (args.change_kind !== undefined)
+                body['change_kind'] = args.change_kind;
+            if (args.change !== undefined)
+                body['change'] = args.change;
+            if (args.preview_token !== undefined)
+                body['preview_token'] = args.preview_token;
+            return await client.postJson('/api/structured/change-plan', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_focus',
+        description: 'Immediate compatibility write for a focus change the author has already authorized exactly; otherwise use novel_structured_change_plan. Set the writing focus compass for the project.',
+        parameters: {
+            goal: { type: 'string', required: true, description: 'The current writing goal.' },
+            must_keep: { type: 'array', items: { type: 'string' }, description: 'Constraints that must be kept.' },
+            must_avoid: { type: 'array', items: { type: 'string' }, description: 'Things that must be avoided.' },
+            notes: { type: 'array', items: { type: 'string' }, description: 'Free-form focus notes.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { goal: args.goal };
+            if (args.must_keep !== undefined)
+                body['must_keep'] = args.must_keep;
+            if (args.must_avoid !== undefined)
+                body['must_avoid'] = args.must_avoid;
+            if (args.notes !== undefined)
+                body['notes'] = args.notes;
+            return await client.postJson('/api/focus', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_export_preflight',
+        description: 'Inspect the current manuscript export order, structural defects, writing targets, metadata, review freshness, ' +
+            'manuscript acceptance, blockers, and warnings. Pass the returned preflight_revision unchanged to novel_export ' +
+            'so the downloaded file is bound to the manuscript state that was inspected.',
+        parameters: {
+            format: { type: 'string', enum: ['md', 'txt', 'epub'], description: 'Export format (default "md").' },
+            purpose: { type: 'string', enum: ['backup', 'delivery'], description: 'Export purpose (default "delivery"). Delivery applies publication gates; backup preserves the current work.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/export/preflight', {
+                format: args.format ?? 'md',
+                purpose: args.purpose ?? 'delivery',
+            }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_export',
+        description: 'Export the manuscript as a file download and save it locally. Inspect novel_export_preflight first and pass its ' +
+            'preflight_revision unchanged to bind the download to that inspected manuscript state. Returns the saved file path.',
+        parameters: {
+            format: { type: 'string', enum: ['md', 'txt', 'epub'], description: 'Export format (default "md").' },
+            purpose: { type: 'string', enum: ['backup', 'delivery'], description: 'Export purpose (default "delivery").' },
+            preflight_revision: { type: 'string', description: 'Revision returned by novel_export_preflight for the same format and purpose.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true, description: 'Absolute path of the saved export file.' },
+                    filename: { type: 'string', required: true },
+                    format: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Exported ${value.filename} (${value.bytes} bytes) to ${value.path}`,
+                }],
+        },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const format = args.format ?? 'md';
+            const purpose = args.purpose ?? 'delivery';
+            const download = await client.download('/api/export', {
+                format,
+                purpose,
+                ...(args.preflight_revision === undefined ? {} : { preflight_revision: args.preflight_revision }),
+            }, exec.signal);
+            const filename = exportFilename(download.filename, `novel.${format}`);
+            const exportDir = outputDirFor(outputDir, client);
+            await mkdir(exportDir, { recursive: true });
+            const path = join(exportDir, filename);
+            await writeFile(path, download.content);
+            return { path, filename, format, bytes: download.content.byteLength };
+        },
+    }));
+    // ── assets: create / read / packages ────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_asset_read',
+        description: 'Read one structured asset by kind and id, including its relation view.',
+        parameters: {
+            kind: { type: 'string', required: true, enum: ['character', 'world', 'progression'], description: 'Asset kind.' },
+            id: { type: 'string', required: true, description: 'Asset id.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/.test(args.id))
+                throw new Error(`invalid asset id "${args.id}"`);
+            return await client.getJson(`/api/assets/${args.kind}/${encodeURIComponent(args.id)}`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_asset_create',
+        description: 'Create a structured asset. character/world assets take front-matter fields via `data` plus an optional ' +
+            '`body_markdown`; progression assets take their YAML mapping via `data`. Fails with a conflict if the id exists — ' +
+            'use novel_asset_update instead.',
+        parameters: {
+            kind: { type: 'string', required: true, enum: ['character', 'world', 'progression'], description: 'Asset kind.' },
+            id: { type: 'string', required: true, description: 'Asset id (letters, digits, "_", "-", ".").' },
+            data: { type: 'json', description: 'Object of asset fields (e.g. name, summary, aliases).' },
+            body_markdown: { type: 'string', description: 'Markdown body (character/world assets).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/.test(args.id))
+                throw new Error(`invalid asset id "${args.id}"`);
+            const body = { kind: args.kind, id: args.id };
+            if (args.data !== undefined)
+                body['data'] = args.data;
+            if (args.body_markdown !== undefined)
+                body['body_markdown'] = args.body_markdown;
+            return await client.postJson('/api/assets', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_assets_package_export',
+        description: 'Export assets as an .owasset.zip package and save it locally. Omit selections to export all assets.',
+        parameters: {
+            selections: { type: 'array', items: { type: 'string' }, description: 'Asset selectors in "kind:id" form, e.g. ["character:hero", "world:capital"].' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true, description: 'Absolute path of the saved package file.' },
+                    filename: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Exported asset package ${value.filename} (${value.bytes} bytes) to ${value.path}`,
+                }],
+        },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const selections = args.selections ?? [];
+            for (const item of selections) {
+                if (!/^(character|world|progression):[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/.test(item)) {
+                    throw new Error(`invalid asset selection "${item}"; expected "kind:id"`);
+                }
+            }
+            const download = await client.download('/api/assets/package/export', { select: selections }, exec.signal);
+            const filename = exportFilename(download.filename, 'assets.owasset.zip');
+            const exportDir = outputDirFor(outputDir, client);
+            await mkdir(exportDir, { recursive: true });
+            const path = join(exportDir, filename);
+            await writeFile(path, download.content);
+            return { path, filename, bytes: download.content.byteLength };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_assets_package_preview',
+        description: 'Stage an .owasset.zip asset package (base64) and preview its contents and conflicts without importing. ' +
+            'Returns an upload_id to pass to novel_assets_package_import.',
+        parameters: {
+            package_base64: { type: 'string', required: true, description: 'Base64-encoded .owasset.zip package (max 25 MB decoded).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.package_base64.trim())
+                throw new Error('package_base64 must be a non-empty string');
+            return await client.postJson('/api/assets/package/preview', { package_base64: args.package_base64 }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_assets_package_import',
+        description: 'Import a previously staged asset package (see novel_assets_package_preview). Resolves per-asset conflicts ' +
+            'via `resolutions`; set allow_missing_dependencies to skip missing dependency checks.',
+        parameters: {
+            upload_id: { type: 'string', required: true, description: 'The upload_id returned by novel_assets_package_preview.' },
+            package_sha256: { type: 'string', description: 'Optional expected package digest guard.' },
+            resolutions: { type: 'json', description: 'Object mapping conflicting asset keys to resolutions.' },
+            allow_missing_dependencies: { type: 'boolean', description: 'Allow import despite missing asset dependencies (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { upload_id: args.upload_id };
+            if (args.package_sha256 !== undefined)
+                body['package_sha256'] = args.package_sha256;
+            if (args.resolutions !== undefined)
+                body['resolutions'] = args.resolutions;
+            if (args.allow_missing_dependencies !== undefined)
+                body['allow_missing_dependencies'] = args.allow_missing_dependencies;
+            return await client.postJson('/api/assets/package/import', body, exec.signal);
+        },
+    }));
+    // ── revisions ────────────────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_revisions_list',
+        description: 'List revision proposals, optionally filtered by chapter and/or status.',
+        parameters: {
+            chapter: { type: 'string', description: 'Chapter id filter (e.g. "ch_0007").' },
+            status: { type: 'string', description: 'Status filter (e.g. "proposed", "applied", "rejected").' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const params = {};
+            if (args.chapter !== undefined)
+                params['chapter'] = args.chapter;
+            if (args.status !== undefined)
+                params['status'] = args.status;
+            return await client.getJson('/api/revisions', params, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_revision_get',
+        description: 'Get one revision proposal with its diff hunks by proposal id (rev_*).',
+        parameters: {
+            proposal_id: { type: 'string', required: true, description: 'Revision proposal id (rev_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^rev_[A-Za-z0-9_-]+$/.test(args.proposal_id))
+                throw new Error(`invalid proposal_id "${args.proposal_id}"`);
+            return await client.getJson(`/api/revisions/${encodeURIComponent(args.proposal_id)}`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_revision_create_selection',
+        description: 'Create a revision proposal for a text selection in a chapter (LONG-RUNNING, model-generated). ' +
+            'start/end are character offsets; pass the selected text as original_text. The proposal is only staged — ' +
+            'apply it with novel_revision_apply.',
+        parameters: {
+            chapter_id: { type: 'string', required: true, description: 'Chapter id (ch_<digits>).' },
+            start: { type: 'integer', required: true, description: 'Selection start offset.' },
+            end: { type: 'integer', required: true, description: 'Selection end offset.' },
+            original_text: { type: 'string', description: 'The selected original text.' },
+            instruction: { type: 'string', description: 'Revision instruction (max 4000 characters).' },
+            action: { type: 'string', enum: ['rewrite', 'expand', 'compress', 'pace', 'dialogue', 'naturalize', 'custom'], description: 'Revision mode (default "rewrite").' },
+            target_units: { type: 'integer', description: 'Target length in writing units (0 = keep similar).' },
+            full_chapter: { type: 'boolean', description: 'Treat the whole chapter as the selection (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!CHAPTER_ID_PATTERN.test(args.chapter_id))
+                throw new Error(`chapter_id must match ch_<digits>, got "${args.chapter_id}"`);
+            const body = { chapter_id: args.chapter_id, start: args.start, end: args.end };
+            if (args.original_text !== undefined)
+                body['original_text'] = args.original_text;
+            if (args.instruction !== undefined)
+                body['instruction'] = args.instruction;
+            if (args.action !== undefined)
+                body['action'] = args.action;
+            if (args.target_units !== undefined)
+                body['target_units'] = args.target_units;
+            if (args.full_chapter !== undefined)
+                body['full_chapter'] = args.full_chapter;
+            return await client.postJson('/api/revisions/selection', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_revision_create_from_review',
+        description: 'Create a revision proposal that addresses selected issues from a chapter review (LONG-RUNNING, model-generated). ' +
+            'Issue ids come from novel_review_chapter\'s issue_details. The proposal is only staged — apply it with novel_revision_apply.',
+        parameters: {
+            chapter_id: { type: 'string', required: true, description: 'Chapter id (ch_<digits>).' },
+            issue_ids: { type: 'array', required: true, items: { type: 'string' }, description: 'Review issue ids to fix.' },
+            instruction: { type: 'string', description: 'Additional revision instruction.' },
+            target_units: { type: 'integer', description: 'Target length in writing units (0 = keep similar).' },
+            expected_review_revision: { type: 'string', description: 'Exact review file revision from the chapter work brief.' },
+            expected_document_revision: { type: 'string', description: 'Exact manuscript revision from the chapter work brief.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!CHAPTER_ID_PATTERN.test(args.chapter_id))
+                throw new Error(`chapter_id must match ch_<digits>, got "${args.chapter_id}"`);
+            if (args.issue_ids.length === 0)
+                throw new Error('issue_ids must be a non-empty array');
+            const body = { chapter_id: args.chapter_id, issue_ids: args.issue_ids };
+            if (args.instruction !== undefined)
+                body['instruction'] = args.instruction;
+            if (args.target_units !== undefined)
+                body['target_units'] = args.target_units;
+            if (args.expected_review_revision !== undefined)
+                body['expected_review_revision'] = args.expected_review_revision;
+            if (args.expected_document_revision !== undefined)
+                body['expected_document_revision'] = args.expected_document_revision;
+            const response = await client.postJson('/api/revisions/from-review', body, exec.signal);
+            try {
+                return { ...objectValue(response), dog_delivery: await deliveryForResponse(client, response, args.chapter_id, exec.signal) };
+            }
+            catch (error) {
+                return { ...objectValue(response), dog_delivery: { status: 'unavailable', error: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_revision_apply',
+        description: 'Apply a staged revision proposal to the manuscript. Optionally override the generated text or apply only ' +
+            'selected diff hunks. Fails with a conflict if the document changed since the proposal was created.',
+        parameters: {
+            proposal_id: { type: 'string', required: true, description: 'Revision proposal id (rev_*).' },
+            replacement_text: { type: 'string', description: 'Replacement text overriding the proposal.' },
+            selected_hunk_ids: { type: 'array', items: { type: 'string' }, description: 'Apply only these diff hunk ids.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^rev_[A-Za-z0-9_-]+$/.test(args.proposal_id))
+                throw new Error(`invalid proposal_id "${args.proposal_id}"`);
+            const body = {};
+            if (args.replacement_text !== undefined)
+                body['replacement_text'] = args.replacement_text;
+            if (args.selected_hunk_ids !== undefined)
+                body['selected_hunk_ids'] = args.selected_hunk_ids;
+            const response = await client.postJson(`/api/revisions/${encodeURIComponent(args.proposal_id)}/apply`, body, exec.signal);
+            const responseValue = objectValue(response);
+            const proposal = objectValue(responseValue['proposal'] ?? response);
+            const chapterId = String(proposal['chapter_id'] ?? '');
+            try {
+                return { ...objectValue(response), dog_delivery: await deliveryForResponse(client, response, chapterId, exec.signal) };
+            }
+            catch (error) {
+                return { ...objectValue(response), dog_delivery: { status: 'unavailable', error: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_revision_reject',
+        description: 'Reject and discard a staged revision proposal. This permanently drops the generated text — it cannot be ' +
+            'recovered except by regenerating.',
+        parameters: {
+            proposal_id: { type: 'string', required: true, description: 'Revision proposal id (rev_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^rev_[A-Za-z0-9_-]+$/.test(args.proposal_id))
+                throw new Error(`invalid proposal_id "${args.proposal_id}"`);
+            const response = await client.postJson(`/api/revisions/${encodeURIComponent(args.proposal_id)}/reject`, {}, exec.signal);
+            const chapterId = String(objectValue(response)['chapter_id'] ?? '');
+            try {
+                return { ...objectValue(response), dog_delivery: await deliveryForResponse(client, response, chapterId, exec.signal) };
+            }
+            catch (error) {
+                return { ...objectValue(response), dog_delivery: { status: 'unavailable', error: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_revision_regenerate',
+        description: 'Regenerate the text of a staged revision proposal (LONG-RUNNING, model-generated).',
+        parameters: {
+            proposal_id: { type: 'string', required: true, description: 'Revision proposal id (rev_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^rev_[A-Za-z0-9_-]+$/.test(args.proposal_id))
+                throw new Error(`invalid proposal_id "${args.proposal_id}"`);
+            const response = await client.postJson(`/api/revisions/${encodeURIComponent(args.proposal_id)}/regenerate`, {}, exec.signal);
+            const chapterId = String(objectValue(response)['chapter_id'] ?? '');
+            try {
+                return { ...objectValue(response), dog_delivery: await deliveryForResponse(client, response, chapterId, exec.signal) };
+            }
+            catch (error) {
+                return { ...objectValue(response), dog_delivery: { status: 'unavailable', error: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    }));
+    // ── background tasks ─────────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_tasks_list',
+        description: 'List background tasks (queued/running/finished AI jobs) with per-status counts.',
+        parameters: {
+            limit: { type: 'integer', description: 'Maximum number of tasks (server default 100).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const params = {};
+            if (args.limit !== undefined)
+                params['limit'] = String(args.limit);
+            return await client.getJson('/api/tasks', params, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_task_get',
+        description: 'Get one background task with its event log by task id (tsk_*). Completed chapter write/review/revision tasks refresh the chapter-delivery DoG graph; chapter reviews also materialize the 37-dimension graph.',
+        parameters: {
+            task_id: { type: 'string', required: true, description: 'Task id (tsk_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^tsk_[A-Za-z0-9_-]+$/.test(args.task_id))
+                throw new Error(`invalid task_id "${args.task_id}"`);
+            const response = await client.getJson(`/api/tasks/${encodeURIComponent(args.task_id)}`, {}, exec.signal);
+            const responseRecord = response !== null && typeof response === 'object' && !Array.isArray(response)
+                ? response
+                : {};
+            const taskValue = responseRecord['task'] ?? response;
+            const taskRecord = taskValue !== null && typeof taskValue === 'object' && !Array.isArray(taskValue)
+                ? taskValue
+                : {};
+            if (taskRecord['status'] !== 'completed')
+                return response;
+            const taskType = String(taskRecord['type'] ?? '');
+            if (!['chapter_write', 'chapter_review', 'revision_from_review'].includes(taskType))
+                return response;
+            const taskResult = objectValue(taskRecord['result']);
+            const taskInput = objectValue(taskRecord['input']);
+            const chapterId = String(taskRecord['chapter_id'] ?? taskResult['chapter_id'] ?? '').trim()
+                || String(taskInput['path'] ?? '').match(/(?:^|\/)(ch_\d+)\.md$/)?.[1]
+                || '';
+            const value = response !== null && typeof response === 'object' && !Array.isArray(response)
+                ? response
+                : { task: response };
+            if (!/^ch_\d+$/.test(chapterId)) {
+                return { ...value, dog_delivery: { status: 'unavailable', error: 'completed chapter task lacks a resolvable chapter id' } };
+            }
+            let workspace;
+            try {
+                workspace = await client.getJson('/api/workspace', {}, exec.signal);
+            }
+            catch (error) {
+                const unavailable = { status: 'unavailable', error: error instanceof Error ? error.message : String(error) };
+                return taskType === 'chapter_review'
+                    ? { ...value, dog_review: unavailable, dog_delivery: unavailable }
+                    : { ...value, dog_delivery: unavailable };
+            }
+            let dogDelivery;
+            try {
+                dogDelivery = await materializeChapterDelivery(workspace, chapterId, undefined, client.context?.workspaceRoot);
+            }
+            catch (error) {
+                dogDelivery = { status: 'unavailable', error: error instanceof Error ? error.message : String(error) };
+            }
+            if (taskType !== 'chapter_review')
+                return { ...value, dog_delivery: dogDelivery };
+            let dogReview;
+            try {
+                const framework = await client.getJson('/api/review/framework', {}, exec.signal);
+                dogReview = await materializeCompletedDogTaskReview(response, workspace, framework, 70, client.context?.workspaceRoot) ?? { status: 'unavailable', error: 'review task was not materialized' };
+            }
+            catch (error) {
+                dogReview = { status: 'unavailable', error: error instanceof Error ? error.message : String(error) };
+            }
+            return { ...value, dog_review: dogReview, dog_delivery: dogDelivery };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_task_create',
+        description: 'Queue a background AI task and return immediately; poll with novel_task_get. Task types and their `input` keys: ' +
+            'chapter_write {chapter_id?, guidance?, target_words?, temperature?, outline_revision?}; ' +
+            'chapter_review {chapter_id | path, strict?, dimensions?}; ' +
+            'revision_selection / revision_from_review (same inputs as the novel_revision_create_* tools); ' +
+            'source_operation / reference_operation (same inputs as novel_source_action / novel_reference_library_action); ' +
+            'manuscript_import (same input as novel_import); research {prompt, search?, language?, quality?, llm?}; ' +
+            'manuscript_reconcile (durable acceptance analysis; usually started through novel_manuscript_acceptance_reconcile); ' +
+            'settle_backfill {chapter_ids?, only_missing?} — prefer the novel_settle_backfill convenience tool; ' +
+            'continuous_write — prefer the novel_multi_write convenience tool.',
+        parameters: {
+            type: {
+                type: 'string',
+                required: true,
+                enum: ['chapter_write', 'chapter_review', 'revision_selection', 'revision_from_review', 'source_operation', 'reference_operation', 'manuscript_import', 'manuscript_reconcile', 'continuous_write', 'research', 'settle_backfill'],
+                description: 'Task type.',
+            },
+            input: { type: 'json', required: true, description: 'Task input object; shape depends on the task type (see description).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (typeof args.input !== 'object' || args.input === null || Array.isArray(args.input)) {
+                throw new Error('input must be a JSON object');
+            }
+            return await client.postJson('/api/tasks', { type: args.type, input: args.input }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_task_cancel',
+        description: 'Cancel a queued or running background task. Cancellation is permanent for that task; retry with novel_task_retry if the type supports it.',
+        parameters: {
+            task_id: { type: 'string', required: true, description: 'Task id (tsk_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^tsk_[A-Za-z0-9_-]+$/.test(args.task_id))
+                throw new Error(`invalid task_id "${args.task_id}"`);
+            return await client.postJson(`/api/tasks/${encodeURIComponent(args.task_id)}/cancel`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_task_retry',
+        description: 'Retry a failed or cancelled background task.',
+        parameters: {
+            task_id: { type: 'string', required: true, description: 'Task id (tsk_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^tsk_[A-Za-z0-9_-]+$/.test(args.task_id))
+                throw new Error(`invalid task_id "${args.task_id}"`);
+            return await client.postJson(`/api/tasks/${encodeURIComponent(args.task_id)}/retry`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_task_confirm',
+        description: 'Confirm a background task that is awaiting confirmation (e.g. a continuous_write run paused between chapters), letting it resume.',
+        parameters: {
+            task_id: { type: 'string', required: true, description: 'Task id (tsk_*).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^tsk_[A-Za-z0-9_-]+$/.test(args.task_id))
+                throw new Error(`invalid task_id "${args.task_id}"`);
+            return await client.postJson(`/api/tasks/${encodeURIComponent(args.task_id)}/confirm`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_multi_write',
+        description: 'Queue a BACKGROUND continuous-writing run: writes up to max_chapters chapters following the outline, ' +
+            'reviewing each; stops early on review blockers, continuity errors, low scores, or budget limits. ' +
+            'Returns immediately with a task id — poll with novel_task_get and resume paused runs with novel_task_confirm.',
+        parameters: {
+            max_chapters: { type: 'integer', description: 'Chapters to write, 1-10 (default 1).' },
+            minimum_review_score: { type: 'integer', description: 'Stop when a chapter scores below this, 0-100 (default 82).' },
+            max_tokens: { type: 'integer', description: 'Token budget, 0 = unlimited (default 0).' },
+            max_failures: { type: 'integer', description: 'Stop after this many consecutive failures, 1-10 (default 2).' },
+            max_cost_usd: { type: 'number', description: 'Cost budget in USD, 0 = unlimited (default 0).' },
+            guidance: { type: 'string', description: 'Writing guidance applied to every chapter.' },
+            target_words: { type: 'integer', description: 'Target words per chapter (falls back to the outline recommendation).' },
+            temperature: { type: 'number', description: 'Sampling temperature (default 0.7).' },
+            stop_on_blocker: { type: 'boolean', description: 'Stop when a review reports a blocker issue (default true).' },
+            stop_on_continuity_error: { type: 'boolean', description: 'Stop on high-severity continuity issues (default true).' },
+            require_confirmation_after_each_chapter: { type: 'boolean', description: 'Pause for novel_task_confirm after each chapter (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const input = {};
+            if (args.max_chapters !== undefined)
+                input['max_chapters'] = args.max_chapters;
+            if (args.minimum_review_score !== undefined)
+                input['minimum_review_score'] = args.minimum_review_score;
+            if (args.max_tokens !== undefined)
+                input['max_tokens'] = args.max_tokens;
+            if (args.max_failures !== undefined)
+                input['max_failures'] = args.max_failures;
+            if (args.max_cost_usd !== undefined)
+                input['max_cost_usd'] = args.max_cost_usd;
+            if (args.guidance !== undefined)
+                input['guidance'] = args.guidance;
+            if (args.target_words !== undefined)
+                input['target_words'] = args.target_words;
+            if (args.temperature !== undefined)
+                input['temperature'] = args.temperature;
+            if (args.stop_on_blocker !== undefined)
+                input['stop_on_blocker'] = args.stop_on_blocker;
+            if (args.stop_on_continuity_error !== undefined)
+                input['stop_on_continuity_error'] = args.stop_on_continuity_error;
+            if (args.require_confirmation_after_each_chapter !== undefined)
+                input['require_confirmation_after_each_chapter'] = args.require_confirmation_after_each_chapter;
+            return await client.postJson('/api/tasks', { type: 'continuous_write', input }, exec.signal);
+        },
+    }));
+    // ── project lifecycle ────────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_project_init',
+        description: 'Create a new OpenWrite novel project on the server machine and make it the active project. ' +
+            'Works without a currently open project. novel_id must be 2-64 chars of letters/digits/"-"/"_".',
+        parameters: {
+            novel_id: { type: 'string', required: true, description: 'Project id, e.g. "my_novel" (2-64 chars: letters, digits, "-", "_").' },
+            title: { type: 'string', required: true, description: 'Book title (max 120 characters).' },
+            project_path: { type: 'string', description: 'Target directory on the server; omit to use the server default location.' },
+            template: { type: 'string', enum: ['default', 'demo_short'], description: 'Project template (default "default").' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/.test(args.novel_id)) {
+                throw new Error('novel_id must be 2-64 chars of letters, digits, "-" or "_"');
+            }
+            if (!args.title.trim() || args.title.length > 120)
+                throw new Error('title must be non-empty and at most 120 characters');
+            const body = { novel_id: args.novel_id, title: args.title };
+            if (args.project_path !== undefined)
+                body['project_path'] = args.project_path;
+            if (args.template !== undefined)
+                body['template'] = args.template;
+            return await client.postJson('/api/project/init', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_project_open',
+        description: 'Switch the Studio server to another existing project directory (must contain novel_config.yaml). ' +
+            'Works without a currently open project; afterwards every other novel_* tool targets the newly opened project. ' +
+            'The server rejects the switch while a background task is active.',
+        parameters: {
+            project_path: { type: 'string', required: true, description: 'Absolute project directory path on the server machine.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.project_path.trim())
+                throw new Error('project_path must be a non-empty string');
+            return await client.postJson('/api/project/open', { project_path: args.project_path }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_project_delete',
+        description: 'PERMANENTLY delete a project directory and all its contents from the server machine (recursive delete, ' +
+            'not recoverable). The server requires confirm to exactly equal the project\'s novel_id as a safeguard.',
+        parameters: {
+            project_path: { type: 'string', required: true, description: 'Project directory to delete.' },
+            confirm: { type: 'string', required: true, description: 'Must exactly equal the project\'s novel_id (from its novel_config.yaml).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.project_path.trim() || !args.confirm.trim())
+                throw new Error('project_path and confirm are required');
+            return await client.postJson('/api/project/delete', { project_path: args.project_path, confirm: args.confirm }, exec.signal);
+        },
+    }));
+    // ── chapters, documents, import, sync ────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_chapter_delete',
+        description: 'Delete the LATEST manuscript chapter. The server enforces three safeguards: the path must be a chapter under ' +
+            'data/manuscript, confirm must exactly equal the chapter id (e.g. "ch_0007"), and version must equal the ' +
+            'document version fingerprint from a fresh novel_doc_read. Only the newest chapter can be deleted, and never ' +
+            'while a background task is active.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'Chapter path, e.g. "data/manuscript/ch_0007.md".' },
+            confirm: { type: 'string', required: true, description: 'Must exactly equal the chapter id, e.g. "ch_0007".' },
+            version: { type: 'string', required: true, description: 'The document version fingerprint from novel_doc_read.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            return await client.postJson('/api/chapter/delete', { path: args.path, confirm: args.confirm, version: args.version }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_chapter_delete_batch',
+        description: 'Delete the contiguous latest manuscript tail in one server request, retaining the specified chapter. ' +
+            'The server still performs the single-chapter backup/projection cleanup for every chapter and refuses ' +
+            'active tasks, missing chapters, non-tail ranges, or stale latest-version fingerprints. ' +
+            'confirm must exactly equal "DELETE_AFTER:<keep_through>" (for example "DELETE_AFTER:ch_0030").',
+        parameters: {
+            keep_through: { type: 'string', required: true, description: 'Last chapter to retain, e.g. "ch_0030".' },
+            confirm: { type: 'string', required: true, description: 'Must exactly equal DELETE_AFTER:<keep_through>.' },
+            version: { type: 'string', required: true, description: 'The latest chapter version fingerprint from a fresh novel_doc_read.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            return await client.postJson('/api/chapter/delete-batch', { keep_through: args.keep_through, confirm: args.confirm, version: args.version }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_doc_create',
+        description: 'Create a new project document by kind and name (e.g. a setting or character note), then returns the created document.',
+        parameters: {
+            kind: { type: 'string', required: true, description: 'Document kind (e.g. "setting", "character").' },
+            name: { type: 'string', required: true, description: 'Document name.' },
+            description: { type: 'string', description: 'Short description of the document.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.kind.trim() || !args.name.trim())
+                throw new Error('kind and name must be non-empty strings');
+            const body = { kind: args.kind, name: args.name };
+            if (args.description !== undefined)
+                body['description'] = args.description;
+            return await client.postJson('/api/document/create', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_import_preview',
+        description: 'Preview a TXT/Markdown manuscript import without writing anything: detected chapters, numbering, and ' +
+            'conflicts with existing chapters. Run this before novel_import.',
+        parameters: {
+            content: { type: 'string', required: true, description: 'The manuscript text to import.' },
+            filename: { type: 'string', description: 'Source filename; suffix must be .txt/.md/.markdown (default "import.md").' },
+            arc_id: { type: 'string', description: 'Arc id like "arc_001" (default: the project\'s current arc).' },
+            start_number: { type: 'integer', description: 'First chapter number (default: after the last existing chapter).' },
+            force: { type: 'boolean', description: 'Report the import as allowed despite conflicts (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.content.trim())
+                throw new Error('content must be a non-empty string');
+            const body = { content: args.content };
+            if (args.filename !== undefined)
+                body['filename'] = args.filename;
+            if (args.arc_id !== undefined)
+                body['arc_id'] = args.arc_id;
+            if (args.start_number !== undefined)
+                body['start_number'] = args.start_number;
+            if (args.force !== undefined)
+                body['force'] = args.force;
+            return await client.postJson('/api/import/preview', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_import',
+        description: 'Import a TXT/Markdown manuscript as chapters (split on headings). Preview first with novel_import_preview; ' +
+            'the server rejects conflicting chapter ids unless force is set.',
+        parameters: {
+            content: { type: 'string', required: true, description: 'The manuscript text to import.' },
+            filename: { type: 'string', description: 'Source filename; suffix must be .txt/.md/.markdown (default "import.md").' },
+            arc_id: { type: 'string', description: 'Arc id like "arc_001" (default: the project\'s current arc).' },
+            start_number: { type: 'integer', description: 'First chapter number (default: continue numbering).' },
+            force: { type: 'boolean', description: 'Overwrite conflicting existing chapters (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.content.trim())
+                throw new Error('content must be a non-empty string');
+            const body = { content: args.content };
+            if (args.filename !== undefined)
+                body['filename'] = args.filename;
+            if (args.arc_id !== undefined)
+                body['arc_id'] = args.arc_id;
+            if (args.start_number !== undefined)
+                body['start_number'] = args.start_number;
+            if (args.force !== undefined)
+                body['force'] = args.force;
+            return await client.postJson('/api/import', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_manuscript_import_action',
+        description: 'Operate the durable, resumable import workspace for the author\'s own TXT/Markdown manuscript. ' +
+            'Use list/get to inspect saved operations, prepare to snapshot and split a manuscript, structure to revise the ' +
+            'chapter boundaries against the current preview revision, confirm for explicit structure approval, run to start ' +
+            'or resume the persistent import task, and discard only before publication. This is manuscript migration, not ' +
+            'reference-library analysis.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'get', 'prepare', 'structure', 'confirm', 'run', 'discard'], description: 'Import workspace action.' },
+            import_id: { type: 'string', description: 'Persistent import operation id.' },
+            limit: { type: 'integer', description: 'Maximum operations for list (default 50).' },
+            filename: { type: 'string', description: 'Source filename ending in .txt, .md, or .markdown.' },
+            content: { type: 'string', description: 'The author\'s own manuscript text for prepare.' },
+            arc_id: { type: 'string', description: 'Target arc id, e.g. arc_001.' },
+            start_number: { type: 'integer', description: 'Optional first chapter number.' },
+            expected_preview_revision: { type: 'string', description: 'Current preview revision required by structure/confirm.' },
+            chapters: { type: 'array', items: { type: 'json' }, description: 'Edited chapter objects: chapter_id, title, content.' },
+            confirm: { type: 'boolean', description: 'Must be true for confirm or discard.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const importId = args.import_id?.trim();
+            if (args.action === 'list') {
+                return await client.getJson('/api/manuscript-imports', args.limit === undefined ? {} : { limit: String(args.limit) }, exec.signal);
+            }
+            if (args.action === 'prepare') {
+                if (!args.content?.trim())
+                    throw new Error('prepare requires non-empty content');
+                if (!args.arc_id?.trim())
+                    throw new Error('prepare requires arc_id');
+                const body = { filename: args.filename ?? 'import.md', content: args.content, arc_id: args.arc_id };
+                if (args.start_number !== undefined)
+                    body['start_number'] = args.start_number;
+                return await client.postJson('/api/manuscript-imports/prepare', body, exec.signal);
+            }
+            if (!importId || !/^import_[A-Za-z0-9_-]{12,80}$/.test(importId))
+                throw new Error(`${args.action} requires a valid import_id`);
+            if (args.action === 'get') {
+                return await client.getJson(`/api/manuscript-imports/${encodeURIComponent(importId)}`, {}, exec.signal);
+            }
+            if (args.action === 'structure') {
+                if (!args.expected_preview_revision?.trim())
+                    throw new Error('structure requires expected_preview_revision');
+                if (!Array.isArray(args.chapters) || args.chapters.length === 0)
+                    throw new Error('structure requires non-empty chapters');
+                return await client.postJson('/api/manuscript-imports/structure', {
+                    import_id: importId,
+                    expected_preview_revision: args.expected_preview_revision,
+                    chapters: args.chapters,
+                }, exec.signal);
+            }
+            if (args.action === 'confirm') {
+                if (!args.expected_preview_revision?.trim())
+                    throw new Error('confirm requires expected_preview_revision');
+                if (args.confirm !== true)
+                    throw new Error('confirm requires confirm=true');
+                return await client.postJson('/api/manuscript-imports/confirm', {
+                    import_id: importId,
+                    expected_preview_revision: args.expected_preview_revision,
+                    confirm: true,
+                }, exec.signal);
+            }
+            if (args.action === 'run') {
+                return await client.postJson('/api/manuscript-imports/run', { import_id: importId }, exec.signal);
+            }
+            if (args.confirm !== true)
+                throw new Error('discard requires confirm=true');
+            return await client.postJson('/api/manuscript-imports/discard', { import_id: importId, confirm: true }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_project_archive_action',
+        description: 'Inspect, create, and restore complete .owarchive project archives. Use preflight before create; use ' +
+            'restore_preview before restore to inspect path/reference rewrites, conflicts, warnings, checksum, and the ' +
+            'archived-without-auto-resume task policy. Restore requires the preview archive_sha256 and explicit confirmation.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['preflight', 'list', 'get', 'create', 'restore_preview', 'restore'], description: 'Archive lifecycle action.' },
+            archive_id: { type: 'string', description: 'Archive id shaped owa_<24 lowercase hex>.' },
+            expected_preflight_revision: { type: 'string', description: 'Current archive preflight revision for create.' },
+            target_root: { type: 'string', description: 'Absolute new or empty project directory for restore.' },
+            target_novel_id: { type: 'string', description: 'Optional restored novel id.' },
+            reference_policy: { type: 'string', enum: ['preserve_relative', 'rewrite_novel_id'], description: 'Reference handling during restore.' },
+            archive_sha256: { type: 'string', description: 'Checksum returned by restore_preview.' },
+            confirm: { type: 'boolean', description: 'Must be true for restore.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (args.action === 'preflight')
+                return await client.getJson('/api/project-archives/preflight', {}, exec.signal);
+            if (args.action === 'list')
+                return await client.getJson('/api/project-archives', {}, exec.signal);
+            if (args.action === 'create') {
+                if (!args.expected_preflight_revision?.trim())
+                    throw new Error('create requires expected_preflight_revision');
+                return await client.postJson('/api/project-archives/create', {
+                    expected_preflight_revision: args.expected_preflight_revision,
+                }, exec.signal);
+            }
+            const archiveId = args.archive_id?.trim();
+            if (!archiveId || !/^owa_[0-9a-f]{24}$/.test(archiveId))
+                throw new Error(`${args.action} requires a valid archive_id`);
+            if (args.action === 'get')
+                return await client.getJson(`/api/project-archives/${archiveId}`, {}, exec.signal);
+            if (!args.target_root?.trim())
+                throw new Error(`${args.action} requires target_root`);
+            const body = {
+                archive_id: archiveId,
+                target_root: args.target_root,
+                reference_policy: args.reference_policy ?? 'preserve_relative',
+            };
+            if (args.target_novel_id !== undefined)
+                body['target_novel_id'] = args.target_novel_id;
+            if (args.action === 'restore_preview') {
+                return await client.postJson('/api/project-archives/restore/preview', body, exec.signal);
+            }
+            if (!args.archive_sha256?.trim())
+                throw new Error('restore requires archive_sha256');
+            if (args.confirm !== true)
+                throw new Error('restore requires confirm=true');
+            body['archive_sha256'] = args.archive_sha256;
+            body['confirm'] = true;
+            return await client.postJson('/api/project-archives/restore', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_project_archive_download',
+        description: 'Download one complete .owarchive project archive and save it in this workspace\'s local export directory.',
+        parameters: {
+            archive_id: { type: 'string', required: true, description: 'Archive id shaped owa_<24 lowercase hex>.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    filename: { type: 'string', required: true },
+                    archive_id: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `Downloaded ${value.filename} (${value.bytes} bytes) to ${value.path}` }],
+        },
+        timeoutMs,
+        async execute(args, exec) {
+            if (!/^owa_[0-9a-f]{24}$/.test(args.archive_id))
+                throw new Error('archive_id must match owa_<24 lowercase hex>');
+            const client = clientFor(exec);
+            const download = await client.download(`/api/project-archives/${args.archive_id}/download`, {}, exec.signal);
+            const filename = exportFilename(download.filename, `${args.archive_id}.owarchive.zip`);
+            const exportDir = outputDirFor(outputDir, client);
+            await mkdir(exportDir, { recursive: true });
+            const path = join(exportDir, filename);
+            await writeFile(path, download.content);
+            return { path, filename, archive_id: args.archive_id, bytes: download.content.byteLength };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_sync',
+        description: 'Synchronize derived caches that are direct src derivatives: outline hierarchy (data/hierarchy.yaml) and ' +
+            'character cards (data/characters/cards/*.yaml). It does NOT rebuild chapter memory / runtime truth / ' +
+            'character state: those are produced by the chapter-write settlement, so imported or pre-existing chapters ' +
+            'need a one-time novel_settle_backfill. The sync response also reports memory_missing / memory_missing_count.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(_args, exec) {
+            const client = clientFor(exec);
+            return await client.postJson('/api/sync', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_settle_backfill',
+        description: 'Settlement backfill for existing/imported chapters: replay the writer pipeline observer+settler over the ' +
+            'actual chapter prose (never rewriting it) and commit chapter memory, runtime-truth notes and a ' +
+            'character-state index refresh. Run once after importing an old manuscript so later chapters, reviews and ' +
+            'canon/continuity checks have real facts from earlier chapters (without it, review canon stays inconclusive ' +
+            'and context lacks previous-chapter recaps). Returns a background task (tsk_*); poll with novel_task_get.',
+        parameters: {
+            chapter_ids: {
+                type: 'array',
+                description: 'Optional chapter ids to backfill, e.g. ["ch_001","ch_002"]; omit to backfill every chapter missing memory.',
+                items: { type: 'string' },
+            },
+            only_missing: { type: 'boolean', description: 'Skip chapters that already have memory (default true).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const input = {};
+            if (args.chapter_ids !== undefined)
+                input['chapter_ids'] = args.chapter_ids;
+            if (args.only_missing !== undefined)
+                input['only_missing'] = args.only_missing;
+            return await client.postJson('/api/tasks', { type: 'settle_backfill', input }, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_writing_targets',
+        description: 'Immediate compatibility write for targets the author has already authorized exactly; otherwise use ' +
+            'novel_structured_change_plan. Update the project writing targets. Ranges: book_words 10000-5000000, chapter_words 200-12000, ' +
+            'outline_volume_words 100-5000, outline_act_words 80-3000, outline_section_words 50-2000, ' +
+            'outline_chapter_words 30-1000. Omitted fields keep their current values.',
+        parameters: {
+            book_words: { type: 'integer', description: 'Whole-book target word count.' },
+            chapter_words: { type: 'integer', description: 'Default words per chapter.' },
+            outline_volume_words: { type: 'integer', description: 'Outline summary words per volume.' },
+            outline_act_words: { type: 'integer', description: 'Outline summary words per act.' },
+            outline_section_words: { type: 'integer', description: 'Outline summary words per section.' },
+            outline_chapter_words: { type: 'integer', description: 'Outline summary words per chapter.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = {};
+            if (args.book_words !== undefined)
+                body['book_words'] = args.book_words;
+            if (args.chapter_words !== undefined)
+                body['chapter_words'] = args.chapter_words;
+            if (args.outline_volume_words !== undefined)
+                body['outline_volume_words'] = args.outline_volume_words;
+            if (args.outline_act_words !== undefined)
+                body['outline_act_words'] = args.outline_act_words;
+            if (args.outline_section_words !== undefined)
+                body['outline_section_words'] = args.outline_section_words;
+            if (args.outline_chapter_words !== undefined)
+                body['outline_chapter_words'] = args.outline_chapter_words;
+            if (Object.keys(body).length === 0)
+                throw new Error('provide at least one writing target field');
+            return await client.postJson('/api/project/writing-targets', body, exec.signal);
+        },
+    }));
+    // ── continuity & diagnostics ─────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_continuity',
+        description: 'Get the continuity report: unresolved foreshadowing, character state drift, and timeline consistency of the current project.',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/continuity', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_diagnostics',
+        description: 'Run runtime diagnostics over the project (read-only): stuck runs, stale locks, and other operational issues.',
+        parameters: {
+            stuck_minutes: { type: 'integer', description: 'Minutes after which a run counts as stuck (default 30).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = {};
+            if (args.stuck_minutes !== undefined)
+                body['stuck_minutes'] = args.stuck_minutes;
+            return await client.postJson('/api/diagnostics', body, exec.signal);
+        },
+    }));
+    // ── planning: chapter runs, rolling plans, forecasts, manuscript editing ──
+    ctx.tools.register(defineTool({
+        name: 'novel_chapter_run_action',
+        description: 'Manage Chapter Run V2 records (the server\'s per-chapter write/review run ledger). Actions: "list" ' +
+            '(chapter_id?/statuses?/limit?), "get" (run_id), "record_intervention" (run_id + revision + request, ' +
+            'optional scope/risk/affected_items/rewrite_required), "update_intervention" (run_id + revision + ' +
+            'intervention_id + state, optional facts_revision/impact/proposal/confirm — state transitions may require ' +
+            'confirm: true), "cancel" (run_id + revision, optional reason). All mutating actions are revision-gated: ' +
+            'pass the run\'s current revision from a list/get call.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'get', 'record_intervention', 'update_intervention', 'cancel'], description: 'The chapter-run operation.' },
+            run_id: { type: 'string', description: 'Run id (required for get/record_intervention/update_intervention/cancel).' },
+            revision: { type: 'string', description: 'Current run revision (required for mutating actions).' },
+            chapter_id: { type: 'string', description: 'Chapter filter for list.' },
+            statuses: { type: 'array', items: { type: 'string' }, description: 'Status filter for list.' },
+            limit: { type: 'integer', description: 'List limit (default 20).' },
+            scope: { type: 'string', description: 'Intervention scope (default "chapter").' },
+            risk: { type: 'string', description: 'Intervention risk level (default "medium").' },
+            request: { type: 'string', description: 'Intervention request text.' },
+            affected_items: { type: 'json', description: 'Array of affected item ids.' },
+            rewrite_required: { type: 'boolean', description: 'Whether the intervention forces a rewrite.' },
+            intervention_id: { type: 'string', description: 'Intervention id (update_intervention).' },
+            state: { type: 'string', description: 'Target intervention state (update_intervention).' },
+            facts_revision: { type: 'string', description: 'Facts revision for the transition (update_intervention).' },
+            impact: { type: 'json', description: 'Impact array for the transition (update_intervention).' },
+            proposal: { type: 'string', description: 'Proposal text for the transition (update_intervention).' },
+            confirm: { type: 'boolean', description: 'Confirm a gated state transition (default false).' },
+            reason: { type: 'string', description: 'Cancel reason (cancel).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'list' || args.action === 'get',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            for (const key of ['run_id', 'revision', 'chapter_id', 'statuses', 'limit', 'scope', 'risk', 'request', 'affected_items', 'rewrite_required', 'intervention_id', 'state', 'facts_revision', 'impact', 'proposal', 'confirm', 'reason']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/chapter-runs-v2', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_rolling_plan_action',
+        description: 'Manage rolling plan candidates (mid-range plot planning windows). Actions: "list" (limit?), "create" ' +
+            '(current_arc?, window_size? default 50, max 50). current_window/accepted_window is accepted manuscript ' +
+            'facts only; next_window/planned_window is outline plan, not facts. "get" (candidate_id), "stage" ' +
+            '(candidate_id + proposal + revision — stages a plan proposal against the candidate; revision-gated), ' +
+            '"delete" (candidate_id + revision), "apply" (candidate_id + revision — appends staged draft chapters ' +
+            'that do not collide with the canonical outline into src/outline.md; never writes accepted facts).',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'create', 'get', 'stage', 'delete', 'apply'], description: 'The rolling-plan operation.' },
+            limit: { type: 'integer', description: 'List limit (default 20).' },
+            current_arc: { type: 'string', description: 'Current arc id (create).' },
+            window_size: { type: 'integer', description: 'Planning window size in chapters (create, default 50, max 50).' },
+            candidate_id: { type: 'string', description: 'Candidate id (get/stage/delete/apply).' },
+            proposal: { type: 'string', description: 'Plan proposal text (stage).' },
+            revision: { type: 'string', description: 'Candidate revision (stage/delete/apply, revision-gated).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'list' || args.action === 'get',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            for (const key of ['limit', 'current_arc', 'window_size', 'candidate_id', 'proposal', 'revision']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/rolling-plans', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_narrative_forecast_action',
+        description: 'Manage narrative forecasts (branching "what-if" plot projections). Actions: "list" (limit?), "create" ' +
+            '(divergence + anchor_chapter_id?, branch_count default 3, horizon default 5), "get" (forecast_id), ' +
+            '"stage" (forecast_id + branches + revision), "select" (forecast_id + branch_id + revision — commits one ' +
+            'branch; revision-gated).',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'create', 'get', 'stage', 'select'], description: 'The forecast operation.' },
+            limit: { type: 'integer', description: 'List limit (default 20).' },
+            divergence: { type: 'string', description: 'The divergence point description (create).' },
+            anchor_chapter_id: { type: 'string', description: 'Chapter to anchor the forecast at (create).' },
+            branch_count: { type: 'integer', description: 'Number of branches (create, default 3).' },
+            horizon: { type: 'integer', description: 'Forecast horizon in chapters (create, default 5).' },
+            forecast_id: { type: 'string', description: 'Forecast id (get/stage/select).' },
+            branches: { type: 'json', description: 'Branch array to stage (stage).' },
+            branch_id: { type: 'string', description: 'Branch id to commit (select).' },
+            revision: { type: 'string', description: 'Forecast revision (stage/select, revision-gated).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'list' || args.action === 'get',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            for (const key of ['limit', 'divergence', 'anchor_chapter_id', 'branch_count', 'horizon', 'forecast_id', 'branches', 'branch_id', 'revision']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/narrative-forecasts', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_manuscript_edit_action',
+        description: 'Chapter version snapshots and annotations. Actions: "versions" (chapter_id), "version" (chapter_id + ' +
+            'version_id — returns the snapshot content), "checkpoint" (chapter_id, optional label — save a snapshot), ' +
+            '"compare" (chapter_id + version_id — preview current-to-snapshot differences without writing), ' +
+            '"restore" (chapter_id + version_id + revision — REVERTS the chapter to a snapshot; revision-gated and ' +
+            'confirmation-gated: the server demands confirm: true), "annotations" (chapter_id), "annotate" (chapter_id + ' +
+            'revision + quote + note, optional start_hint/end_hint and color amber|rose|sky|lime|violet), ' +
+            '"resolve_annotation" (chapter_id + annotation_id).',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['versions', 'version', 'compare', 'checkpoint', 'restore', 'annotations', 'annotate', 'resolve_annotation'], description: 'The manuscript-editing operation.' },
+            chapter_id: { type: 'string', required: true, description: 'Chapter id (ch_<digits>).' },
+            version_id: { type: 'string', description: 'Snapshot id (version/restore).' },
+            label: { type: 'string', description: 'Snapshot label (checkpoint).' },
+            revision: { type: 'string', description: 'Current chapter revision (restore/annotate).' },
+            confirm: { type: 'boolean', description: 'Confirm a restore (required by the server).' },
+            quote: { type: 'string', description: 'Annotated passage (annotate).' },
+            note: { type: 'string', description: 'Annotation note (annotate).' },
+            start_hint: { type: 'integer', description: 'Approximate start offset (annotate).' },
+            end_hint: { type: 'integer', description: 'Approximate end offset (annotate).' },
+            color: { type: 'string', enum: ['amber', 'rose', 'sky', 'lime', 'violet'], description: 'Display color for a selection note (annotate).' },
+            annotation_id: { type: 'string', description: 'Annotation id (resolve_annotation).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'versions' || args.action === 'version' || args.action === 'compare' || args.action === 'annotations',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!CHAPTER_ID_PATTERN.test(args.chapter_id))
+                throw new Error(`chapter_id must match ch_<digits>, got "${args.chapter_id}"`);
+            const body = { action: args.action, chapter_id: args.chapter_id };
+            for (const key of ['version_id', 'label', 'revision', 'confirm', 'quote', 'note', 'start_hint', 'end_hint', 'color', 'annotation_id']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/manuscript-editing', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_manuscript_acceptance_reconcile',
+        description: 'Reconcile the canonical manuscript acceptance ledger. Actions: "baseline" (accept current text as the ' +
+            'initial baseline), "external" (accept a detected external edit), "resume" (continue a durable incomplete ' +
+            'operation), and "acknowledge" (record that the author reviewed the completed acceptance and impacts). ' +
+            'Each action is mapped to the corresponding OpenWrite acceptance endpoint. Baseline, external, and ' +
+            'acknowledge are confirmation-gated by the server.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['baseline', 'external', 'resume', 'acknowledge'], description: 'The reconciliation action.' },
+            chapter_id: { type: 'string', description: 'Optional chapter id (ch_<digits>); omit for the project-level operation.' },
+            operation_id: { type: 'string', description: 'Durable operation id to resume or acknowledge.' },
+            domains: { type: 'array', items: { type: 'string' }, description: 'Affected domains to acknowledge or retry; acknowledge defaults to outline and foreshadowing.' },
+            confirm: { type: 'boolean', description: 'Explicit confirmation for a gated baseline, external acceptance, or acknowledgement.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            if (args.chapter_id !== undefined && !CHAPTER_ID_PATTERN.test(args.chapter_id)) {
+                throw new Error(`chapter_id must match ch_<digits>, got "${args.chapter_id}"`);
+            }
+            const body = {};
+            for (const key of ['chapter_id', 'operation_id', 'domains', 'confirm']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            if (args.action === 'acknowledge' && args.domains === undefined)
+                body['domains'] = ['outline', 'foreshadowing'];
+            const route = args.action === 'acknowledge' ? 'ack' : args.action === 'resume' ? 'reconcile' : args.action;
+            return await clientFor(exec).postJson(`/api/manuscript/acceptance/${route}`, body, exec.signal);
+        },
+    }));
+    // ── style sources, reference library, runtime skills, rules ──────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_source_action',
+        description: 'Style/setting source pipeline (learning from reference texts). Actions: "extract" (source_id + content, ' +
+            'focus "style"|"setting"), "analyze_v2" (source_id + content, focus as array, optional relative_name/' +
+            'input_budget_tokens), "status_v2" (source_id), "retry_v2" (source_id + chunk_id?), "synthesize_v2" ' +
+            '(source_ids array), "profile_v2" (profile_id), "promotion_preview_v2" (profile_id + target), "promote_v2" ' +
+            '(preview_id, confirm: true to commit), "review" (source_id), "promote" (source_id, target? default "all"), ' +
+            '"synthesize" (source_id). Model-backed actions are LONG-RUNNING.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['extract', 'analyze_v2', 'status_v2', 'retry_v2', 'synthesize_v2', 'profile_v2', 'promotion_preview_v2', 'promote_v2', 'review', 'promote', 'synthesize'], description: 'The source operation.' },
+            source_id: { type: 'string', description: 'Source pack id.' },
+            content: { type: 'string', description: 'Source text (extract/analyze_v2).' },
+            focus: { type: 'json', description: '"style"/"setting" string for extract; array of focus names for analyze_v2.' },
+            relative_name: { type: 'string', description: 'Display filename (analyze_v2, default "source.txt").' },
+            input_budget_tokens: { type: 'integer', description: 'Token budget per analysis chunk (default 12000).' },
+            chunk_id: { type: 'string', description: 'Chunk to retry (retry_v2).' },
+            source_ids: { type: 'array', items: { type: 'string' }, description: 'Sources to synthesize (synthesize_v2).' },
+            profile_id: { type: 'string', description: 'Analysis profile id (profile_v2/promotion_preview_v2).' },
+            target: { type: 'string', description: 'Promotion target (promotion_preview_v2/promote, default "all").' },
+            preview_id: { type: 'string', description: 'Promotion preview id (promote_v2).' },
+            confirm: { type: 'boolean', description: 'Confirm a gated promotion (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'status_v2' || args.action === 'profile_v2' || args.action === 'promotion_preview_v2',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            for (const key of ['source_id', 'content', 'focus', 'relative_name', 'input_budget_tokens', 'chunk_id', 'source_ids', 'profile_id', 'target', 'preview_id', 'confirm']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/source', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_reference_library_action',
+        description: 'Reference-library pipeline (decomposing reference works into structured evidence). Actions: "list", ' +
+            '"prepare" (source_id + content, optional title/relative_name/intent/focus array/input_budget_tokens), ' +
+            '"confirm_structure" (source_id, units? array), "analyze" (source_id, LONG-RUNNING), "status" (source_id), ' +
+            '"retry" (source_id + chunk_id?), "synthesize" (source_ids array), "profile" (profile_id), ' +
+            '"adoption_preview" (profile_id + selections array, optional rejected_item_ids), "adopt" (preview_id, ' +
+            'confirm: true to commit).',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'prepare', 'confirm_structure', 'analyze', 'status', 'retry', 'synthesize', 'profile', 'adoption_preview', 'adopt'], description: 'The reference-library operation.' },
+            source_id: { type: 'string', description: 'Reference source id.' },
+            content: { type: 'string', description: 'Reference text (prepare).' },
+            title: { type: 'string', description: 'Reference title (prepare).' },
+            relative_name: { type: 'string', description: 'Display filename (prepare, default "source.txt").' },
+            intent: { type: 'string', description: 'Analysis intent (prepare, default "reference").' },
+            focus: { type: 'json', description: 'Array of focus names (prepare).' },
+            input_budget_tokens: { type: 'integer', description: 'Token budget per chunk (prepare, default 12000).' },
+            units: { type: 'json', description: 'Confirmed structure units (confirm_structure).' },
+            chunk_id: { type: 'string', description: 'Chunk to retry (retry).' },
+            source_ids: { type: 'array', items: { type: 'string' }, description: 'References to synthesize (synthesize).' },
+            profile_id: { type: 'string', description: 'Analysis profile id (profile/adoption_preview).' },
+            selections: { type: 'json', description: 'Array of adoption selections (adoption_preview).' },
+            rejected_item_ids: { type: 'array', items: { type: 'string' }, description: 'Items to reject (adoption_preview).' },
+            preview_id: { type: 'string', description: 'Adoption preview id (adopt).' },
+            confirm: { type: 'boolean', description: 'Confirm a gated adoption (default false).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'list' || args.action === 'status' || args.action === 'profile' || args.action === 'adoption_preview',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            for (const key of ['source_id', 'content', 'title', 'relative_name', 'intent', 'focus', 'input_budget_tokens', 'units', 'chunk_id', 'source_ids', 'profile_id', 'selections', 'rejected_item_ids', 'preview_id', 'confirm']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/reference-library', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_runtime_skill_action',
+        description: 'Inspect OpenWrite runtime skills. Actions: "list" (all discovered skills), "diagnose" (skill loading ' +
+            'problems), "resolve" (which skills apply for an agent and task — optional agent one of dante/goethe/writer/' +
+            'reviewer/studio, skills, task, intent, document_type). Read-only.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'diagnose', 'resolve'], description: 'The runtime-skill operation.' },
+            agent: { type: 'string', description: 'Agent baseline for resolve: "dante", "goethe", "writer", "reviewer", or "studio" (default).' },
+            skills: { type: 'array', items: { type: 'string' }, description: 'Explicit skill ids to resolve.' },
+            task: { type: 'string', description: 'Task description for resolve.' },
+            intent: { type: 'string', description: 'Intent hint for resolve.' },
+            document_type: { type: 'string', description: 'Document type hint for resolve.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            for (const key of ['agent', 'skills', 'task', 'intent', 'document_type']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/runtime-skills', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_rule_action',
+        description: 'Compiled writing rules. Actions: "status" (active rule set), "preview" (compile a candidate preview), ' +
+            '"apply" (preview_id — confirmation-gated: the server answers CONFIRMATION_REQUIRED until called again ' +
+            'with confirm: true).',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['status', 'preview', 'apply'], description: 'The rule operation.' },
+            preview_id: { type: 'string', description: 'Preview id to apply (apply).' },
+            confirm: { type: 'boolean', description: 'Confirm applying the preview (apply).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: (args) => args.action === 'status',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = { action: args.action };
+            if (args.preview_id !== undefined)
+                body['preview_id'] = args.preview_id;
+            if (args.confirm !== undefined)
+                body['confirm'] = args.confirm;
+            return await client.postJson('/api/rules', body, exec.signal);
+        },
+    }));
+    // ── deep research ────────────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_research_status',
+        description: 'Get the deep-research surface: settings status, report list, and the configured model route. Run a research job via novel_task_create with type "research".',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/research', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_research_report',
+        description: 'Read one deep-research report by id (ids come from novel_research_status).',
+        parameters: {
+            report_id: { type: 'string', required: true, description: 'Report id.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,100}$/.test(args.report_id))
+                throw new Error(`invalid report_id "${args.report_id}"`);
+            return await client.getJson(`/api/research/reports/${encodeURIComponent(args.report_id)}`, {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_research_settings_save',
+        description: 'Save deep-research API settings (search/LLM providers, API keys, defaults). Pass the whole settings object; returns the refreshed research surface.',
+        parameters: {
+            settings: { type: 'json', required: true, description: 'Settings object, e.g. {"search": "bocha", "llm": "deepseek", ...}.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (typeof args.settings !== 'object' || args.settings === null || Array.isArray(args.settings)) {
+                throw new Error('settings must be a JSON object');
+            }
+            return await client.postJson('/api/research/settings', args.settings, exec.signal);
+        },
+    }));
+    // ── model configuration ──────────────────────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'novel_model_profiles',
+        description: 'List the server\'s model profiles and per-task routing (which provider/model OpenWrite uses for writing, review, etc.).',
+        parameters: {},
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            const client = clientFor(exec);
+            return await client.getJson('/api/model/profiles', {}, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_benchmark',
+        description: 'Run or inspect isolated chapter or outline model benchmarks through OpenWrite profiles and LiteLLM. ' +
+            'Use options first to read chapter choices, task limits, supported execution modes and the authoritative ' +
+            'pipeline DAG/review domains without invoking a model. The run action creates a background task and never ' +
+            'changes model routes, canonical manuscript or canonical outline files.',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['list', 'get', 'options', 'run'], description: 'Benchmark operation; options previews task choices and pipeline DAGs without starting a run.' },
+            run_id: { type: 'string', description: 'Benchmark run id for get.' },
+            task_type: { type: 'string', enum: ['chapter', 'outline'], description: 'Run target: chapter (default) or outline. Outline supports framework mode only.' },
+            chapter_id: { type: 'string', description: 'Chapter task target: next (default) or an available canonical chapter_id from options, e.g. ch_003. Unavailable targets are rejected without fallback; inspect availability/reason first.' },
+            outline_start_chapter: { type: 'integer', description: 'Outline task first chapter number, inclusive, 1-100000. Omit to continue after the last outline chapter.' },
+            outline_chapter_count: { type: 'integer', description: 'Outline task range length including its starting chapter, 1-20 (default 3).' },
+            writer_profile_ids: { type: 'array', items: { type: 'string' }, description: 'Writing profiles to compare (run).' },
+            reviewer_profile_ids: { type: 'array', items: { type: 'string' }, description: 'Independent blind-review profiles (run).' },
+            execution_mode: { type: 'string', enum: ['framework', 'creative'], description: 'Execution path: full framework (default); creative diagnostic is available only for chapter tasks. Read task pipelines with options.' },
+            repeats: { type: 'integer', description: 'Repeats per writing profile, 1-5.' },
+            target_words: { type: 'integer', description: 'Chapter candidate target length, 200-12000; use outline_chapter_count for outline range.' },
+            concurrency: { type: 'integer', description: 'Concurrent model jobs, 1-4.' },
+            limit: { type: 'integer', description: 'List limit, default 20.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: args => args.action !== 'run',
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (args.action === 'list') {
+                return await client.getJson('/api/benchmarks', args.limit === undefined ? {} : { limit: String(args.limit) }, exec.signal);
+            }
+            if (args.action === 'options') {
+                return await client.getJson('/api/benchmarks/options', {}, exec.signal);
+            }
+            if (args.action === 'get') {
+                if (!args.run_id?.trim())
+                    throw new Error('run_id is required for get');
+                return await client.getJson(`/api/benchmarks/${encodeURIComponent(args.run_id.trim())}`, {}, exec.signal);
+            }
+            if (!Array.isArray(args.writer_profile_ids) || args.writer_profile_ids.length === 0) {
+                throw new Error('writer_profile_ids is required for run');
+            }
+            if (!Array.isArray(args.reviewer_profile_ids) || args.reviewer_profile_ids.length === 0) {
+                throw new Error('reviewer_profile_ids is required for run');
+            }
+            const body = {
+                writer_profile_ids: args.writer_profile_ids,
+                reviewer_profile_ids: args.reviewer_profile_ids,
+            };
+            for (const key of ['task_type', 'chapter_id', 'outline_start_chapter', 'outline_chapter_count', 'execution_mode', 'repeats', 'target_words', 'concurrency']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/benchmarks', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_configure',
+        description: 'Apply and persist the server\'s active model connection (OpenWrite\'s own LLM for writing/review — ' +
+            'independent of the dsh model). max_tokens must stay below context_tokens.',
+        parameters: {
+            provider: { type: 'string', enum: ['openai', 'anthropic', 'custom'], description: 'Provider (default "openai").' },
+            model: { type: 'string', required: true, description: 'Model name (max 120 characters).' },
+            api_key: { type: 'string', description: 'API key; omit to reuse the server environment key.' },
+            base_url: { type: 'string', description: 'Base URL (required for provider "custom").' },
+            api_format: { type: 'string', enum: ['chat', 'responses'], description: 'API format (default "chat").' },
+            context_tokens: { type: 'integer', description: 'Context budget (min 12000).' },
+            max_tokens: { type: 'integer', description: 'Max output tokens (min 256, must be < context_tokens).' },
+            remember_api_key: { type: 'boolean', description: 'Persist the API key on the server (default true).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.model.trim() || args.model.length > 120)
+                throw new Error('model must be non-empty and at most 120 characters');
+            const body = { model: args.model };
+            for (const key of ['provider', 'api_key', 'base_url', 'api_format', 'context_tokens', 'max_tokens', 'remember_api_key']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/model', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_test',
+        description: 'Test a model connection without changing active settings. Pass id to test a stored profile, or a full ' +
+            'candidate (provider/model/base_url/api_key...).',
+        parameters: {
+            id: { type: 'string', description: 'Stored profile id to test.' },
+            provider: { type: 'string', enum: ['openai', 'anthropic', 'custom'], description: 'Provider (default "openai").' },
+            model: { type: 'string', description: 'Model name (required when id is omitted).' },
+            base_url: { type: 'string', description: 'Base URL (required for provider "custom").' },
+            api_format: { type: 'string', enum: ['chat', 'responses'], description: 'API format (default "chat").' },
+            api_key: { type: 'string', description: 'API key; omit to reuse the server environment key.' },
+            context_tokens: { type: 'integer', description: 'Context budget.' },
+            max_tokens: { type: 'integer', description: 'Max output tokens.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (args.id === undefined && (args.model === undefined || !args.model.trim())) {
+                throw new Error('either id (stored profile) or model (candidate) is required');
+            }
+            const body = {};
+            for (const key of ['id', 'provider', 'model', 'base_url', 'api_format', 'api_key', 'context_tokens', 'max_tokens']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/model/test', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_embedding_test',
+        description: 'Probe an independent Embedding profile without changing Chat profiles.',
+        parameters: {
+            id: { type: 'string', description: 'Stored profile id to probe.' },
+            candidate: { type: 'json', description: 'Embedding candidate settings object (merged into the request).' },
+            api_key: { type: 'string', description: 'Embedding API key override.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            const body = {};
+            if (args.candidate !== undefined) {
+                if (typeof args.candidate !== 'object' || args.candidate === null || Array.isArray(args.candidate)) {
+                    throw new Error('candidate must be a JSON object');
+                }
+                Object.assign(body, args.candidate);
+            }
+            for (const key of ['id', 'api_key']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/model/embedding/test', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_profile_save',
+        description: 'Save (create or update) a named model profile on the server, with an optional API key.',
+        parameters: {
+            profile: { type: 'json', required: true, description: 'Profile object, e.g. {"id": "fast", "label": "...", "provider": "openai", "model": "...", "base_url": "...", "max_output_tokens": 24000}.' },
+            api_key: { type: 'string', description: 'Chat API key to store with the profile.' },
+            remember_api_key: { type: 'boolean', description: 'Persist the API key on the server (default true).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (typeof args.profile !== 'object' || args.profile === null || Array.isArray(args.profile)) {
+                throw new Error('profile must be a JSON object');
+            }
+            const body = { ...args.profile };
+            for (const key of ['api_key', 'remember_api_key']) {
+                const value = args[key];
+                if (value !== undefined)
+                    body[key] = value;
+            }
+            return await client.postJson('/api/model/profiles', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_profile_delete',
+        description: 'Delete a stored model profile. Routes pointing at it fall back to fallback_id.',
+        parameters: {
+            profile_id: { type: 'string', required: true, description: 'Profile id to delete.' },
+            fallback_id: { type: 'string', description: 'Profile id to reroute to (default: the server default profile).' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (!args.profile_id.trim())
+                throw new Error('profile_id must be a non-empty string');
+            const body = { profile_id: args.profile_id };
+            if (args.fallback_id !== undefined)
+                body['fallback_id'] = args.fallback_id;
+            return await client.postJson('/api/model/profiles/delete', body, exec.signal);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'novel_model_routes_save',
+        description: 'Save per-task model routing: map operation names (e.g. "chapter_write", "review", "research") to profile ids.',
+        parameters: {
+            routes: { type: 'json', required: true, description: 'Object mapping operation names to profile ids.' },
+        },
+        output: { schema: JSON_OUTPUT_SCHEMA, render: (_args, value) => renderJson(value) },
+        timeoutMs,
+        async execute(args, exec) {
+            const client = clientFor(exec);
+            if (typeof args.routes !== 'object' || args.routes === null || Array.isArray(args.routes)) {
+                throw new Error('routes must be a JSON object');
+            }
+            return await client.postJson('/api/model/routes', { routes: args.routes }, exec.signal);
+        },
+    }));
+}