@actalk/inkos-core 1.5.0 → 1.6.1

package/dist/agent/agent-tools.js

@@ -2,7 +2,7 @@ import { Type } from "@mariozechner/pi-ai";
 import { ArchitectIncompleteFoundationError } from "../agents/architect.js";
 import { defaultChapterLength } from "../utils/length-metrics.js";
 import { inferLanguage } from "../utils/language.js";
-import { readFile, writeFile, readdir, stat } from "node:fs/promises";
+import { mkdir, readFile, writeFile, readdir, stat } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { StateManager } from "../state/manager.js";
 import { assertSafeTruthFileName, createInteractionToolsFromDeps } from "../interaction/project-tools.js";
@@ -11,10 +11,14 @@ import { assertSafeBookId, deriveBookIdFromTitle } from "../utils/book-id.js";
 import { safeChildPath } from "../utils/path-safety.js";
 import { normalizePlatformId, normalizePlatformOrOther } from "../models/book.js";
 import { generateShortFictionCover, runShortFictionProduction } from "../pipeline/short-fiction-runner.js";
+import { runInteractiveFilmCreation, runScriptCreation, runStoryboardCreation } from "../pipeline/script-storyboard-runner.js";
+import { runResearchReport } from "../agents/researcher.js";
 import { createPlayDB } from "../play/play-db-factory.js";
 import { PlayRunner } from "../play/play-runner.js";
 import { PlayStore } from "../play/play-store.js";
 import { ActionPayloadSchema, isUsablePlayInitialScene } from "../interaction/action-envelope.js";
+import { ResearchSearchConfigSchema } from "../models/project.js";
+import { searchWeb } from "../utils/web-search.js";
 function textResult(text, details) {
     return { content: [{ type: "text", text }], details: details };
 }
@@ -89,6 +93,12 @@ const ProposeActionParams = Type.Object({
         Type.Literal("continuation_import"),
         Type.Literal("spinoff_create"),
         Type.Literal("style_imitation"),
+        Type.Literal("script_create"),
+        Type.Literal("storyboard_create"),
+        Type.Literal("interactive_film_create"),
+        Type.Literal("draft_structure"),
+        Type.Literal("connect_choice"),
+        Type.Literal("remove_node"),
     ], {
         description: "The production or assisted Studio workflow the user appears to want, but which needs explicit confirmation from general chat.",
     }),
@@ -172,12 +182,65 @@ const ProposeActionParams = Type.Object({
         coverPrompt: Type.Optional(Type.String({ description: "Confirmed visual direction." })),
         outputDir: Type.Optional(Type.String({ description: "Confirmed output directory." })),
     }, { description: "Structured execution args for action=generate_cover." })),
+    scriptCreate: Type.Optional(Type.Object({
+        title: Type.Optional(Type.String({ description: "Confirmed script project title." })),
+        sourceKind: Type.Optional(Type.String({ description: "Source type, e.g. novel excerpt, original idea, outline, existing script." })),
+        targetFormat: Type.Optional(Type.Union([
+            Type.Literal("vertical_short_drama"),
+            Type.Literal("screenplay"),
+            Type.Literal("audio_drama"),
+            Type.Literal("interactive_script"),
+            Type.Literal("general_script"),
+        ], { description: "Confirmed script output format." })),
+        sourceText: Type.Optional(Type.String({ description: "User-provided source text. For long sources, prefer sourcePath instead of summarizing." })),
+        sourcePath: Type.Optional(Type.String({ description: "Optional project-relative source file path." })),
+        requirements: Type.Optional(Type.String({ description: "Confirmed script format, production constraints, tone, episode structure, or user preferences." })),
+        episodeCount: Type.Optional(Type.Number({ description: "Optional target episode/segment count." })),
+        episodeDuration: Type.Optional(Type.String({ description: "Optional per-episode/per-segment duration." })),
+        projectId: Type.Optional(Type.String({ description: "Optional output id under dramas/." })),
+        outDir: Type.Optional(Type.String({ description: "Optional project-relative output directory. Default dramas/." })),
+    }, { description: "Structured execution args for action=script_create." })),
+    storyboardCreate: Type.Optional(Type.Object({
+        title: Type.Optional(Type.String({ description: "Confirmed storyboard project title." })),
+        sourceKind: Type.Optional(Type.String({ description: "Source type, e.g. script, novel excerpt, idea, scene list." })),
+        sourceText: Type.Optional(Type.String({ description: "User-provided source text. For long sources, prefer sourcePath instead of summarizing." })),
+        sourcePath: Type.Optional(Type.String({ description: "Optional project-relative source file path." })),
+        requirements: Type.Optional(Type.String({ description: "Confirmed shot/storyboard requirements." })),
+        visualStyle: Type.Optional(Type.String({ description: "Confirmed visual style, if the user specified one." })),
+        aspectRatio: Type.Optional(Type.String({ description: "Confirmed aspect ratio, e.g. 9:16, 16:9, 1:1." })),
+        granularity: Type.Optional(Type.String({ description: "Confirmed storyboard granularity." })),
+        maxShots: Type.Optional(Type.Number({ description: "Optional max shot count." })),
+        projectId: Type.Optional(Type.String({ description: "Optional output id under storyboards/." })),
+        outDir: Type.Optional(Type.String({ description: "Optional project-relative output directory. Default storyboards/." })),
+    }, { description: "Structured execution args for action=storyboard_create." })),
+    interactiveFilmCreate: Type.Optional(Type.Object({
+        title: Type.Optional(Type.String({ description: "Confirmed interactive-film project title." })),
+        sourceKind: Type.Optional(Type.String({ description: "Source type, e.g. novel excerpt, script, outline, original idea." })),
+        sourceText: Type.Optional(Type.String({ description: "User-provided source text. For long sources, prefer sourcePath instead of summarizing." })),
+        sourcePath: Type.Optional(Type.String({ description: "Optional project-relative source file path." })),
+        requirements: Type.Optional(Type.String({ description: "Confirmed branching, variable/flag, ending, production, visual, or market requirements." })),
+        targetAudience: Type.Optional(Type.String({ description: "Confirmed target audience or market." })),
+        episodeCount: Type.Optional(Type.Number({ description: "Optional target episode/segment count." })),
+        episodeDuration: Type.Optional(Type.String({ description: "Optional per-episode/per-segment duration." })),
+        budget: Type.Optional(Type.String({ description: "Optional budget or production constraints." })),
+        referenceMode: Type.Optional(Type.String({ description: "Optional reference mode, e.g. 盛世天下-style multi-ending interactive drama." })),
+        projectId: Type.Optional(Type.String({ description: "Optional output id under interactive-films/." })),
+        outDir: Type.Optional(Type.String({ description: "Optional project-relative output directory. Default interactive-films/." })),
+    }, { description: "Structured execution args for action=interactive_film_create." })),
 });
 function proposedActionSessionKind(action) {
     if (action === "create_book")
         return "book-create";
     if (action === "play_start")
         return "play";
+    if (action === "script_create")
+        return "script";
+    if (action === "storyboard_create")
+        return "storyboard";
+    if (action === "interactive_film_create")
+        return "interactive-film";
+    if (action === "draft_structure" || action === "connect_choice" || action === "remove_node")
+        return "interactive-film-authoring";
     if (action === "fanfic_init" || action === "continuation_import" || action === "spinoff_create" || action === "style_imitation")
         return "chat";
     return "short";
@@ -211,6 +274,18 @@ function proposedActionFallbackTitle(action, isZh) {
             return isZh ? "打开番外创作" : "Open side-story workflow";
         case "style_imitation":
             return isZh ? "打开仿写/文风分析" : "Open style imitation";
+        case "script_create":
+            return isZh ? "创建剧本" : "Create script";
+        case "storyboard_create":
+            return isZh ? "创建分镜" : "Create storyboard";
+        case "interactive_film_create":
+            return isZh ? "创建互动影游" : "Create interactive film";
+        case "draft_structure":
+            return isZh ? "生成故事结构" : "Draft story structure";
+        case "connect_choice":
+            return isZh ? "连接选项" : "Connect choice";
+        case "remove_node":
+            return isZh ? "删除节点" : "Remove node";
     }
 }
 function proposedActionFallbackSummary(action, isZh) {
@@ -241,6 +316,11 @@ function compactObject(value) {
                 out[key] = items;
             continue;
         }
+        if (typeof raw === "number") {
+            if (Number.isFinite(raw) && raw > 0)
+                out[key] = raw;
+            continue;
+        }
         if (raw !== undefined && raw !== null) {
             out[key] = raw;
         }
@@ -295,6 +375,21 @@ function proposedActionPayload(params) {
         if (generateCover)
             payload.generateCover = generateCover;
     }
+    if (params.action === "script_create") {
+        const scriptCreate = compactObject(params.scriptCreate);
+        if (scriptCreate)
+            payload.scriptCreate = scriptCreate;
+    }
+    if (params.action === "storyboard_create") {
+        const storyboardCreate = compactObject(params.storyboardCreate);
+        if (storyboardCreate)
+            payload.storyboardCreate = storyboardCreate;
+    }
+    if (params.action === "interactive_film_create") {
+        const interactiveFilmCreate = compactObject(params.interactiveFilmCreate);
+        if (interactiveFilmCreate)
+            payload.interactiveFilmCreate = interactiveFilmCreate;
+    }
     return Object.keys(payload).length > 0 ? payload : undefined;
 }
 function validateProposedActionPayload(payload) {
@@ -323,6 +418,18 @@ function assertExecutableProposedAction(params, payload) {
     }
     if (params.action === "generate_cover") {
         requireProposedText(payload?.generateCover?.title, "generateCover.title");
+        return;
+    }
+    if (params.action === "script_create") {
+        requireProposedText(payload?.scriptCreate?.title, "scriptCreate.title");
+        return;
+    }
+    if (params.action === "storyboard_create") {
+        requireProposedText(payload?.storyboardCreate?.title, "storyboardCreate.title");
+        return;
+    }
+    if (params.action === "interactive_film_create") {
+        requireProposedText(payload?.interactiveFilmCreate?.title, "interactiveFilmCreate.title");
     }
 }
 export function createProposeActionTool(language = "zh", options = {}) {
@@ -620,7 +727,97 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
     };
 }
 // ---------------------------------------------------------------------------
-// 2. Standalone Short Fiction Tool
+// 2. Research Tool (research_web)
+// ---------------------------------------------------------------------------
+const ResearchWebParams = Type.Object({
+    topic: Type.String({
+        description: "Research question or topic, e.g. 1990s county cold-storage accounting workflow or Tang dynasty courier stations.",
+    }),
+    purpose: Type.Union([
+        Type.Literal("worldbuilding"),
+        Type.Literal("era"),
+        Type.Literal("profession"),
+        Type.Literal("market"),
+        Type.Literal("fact-check"),
+        Type.Literal("general"),
+    ], {
+        description: "Why this research is needed. Research reports are references only and must not directly mutate story state.",
+    }),
+    depth: Type.Optional(Type.Union([
+        Type.Literal("quick"),
+        Type.Literal("standard"),
+        Type.Literal("deep"),
+    ], {
+        description: "Research depth. Default standard.",
+    })),
+});
+export function createResearchWebTool(projectRoot) {
+    return {
+        name: "research_web",
+        description: "Collect traceable web research for worldbuilding, era, profession, market, or fact-check questions. " +
+            "Saves a Markdown report under .inkos/research/. It is reference material only; it must not modify books, chapters, or truth files.",
+        label: "Research Web",
+        parameters: ResearchWebParams,
+        async execute(_toolCallId, params, _signal, onUpdate) {
+            onUpdate?.(textResult(`Researching: ${params.topic}`));
+            const searchConfig = await readResearchSearchConfig(projectRoot);
+            const searchOptions = searchConfig.enabled
+                ? {
+                    apiKey: searchConfig.apiKey,
+                    apiKeyEnv: searchConfig.apiKeyEnv,
+                    baseUrl: searchConfig.baseUrl,
+                }
+                : {};
+            const report = await runResearchReport({
+                topic: params.topic,
+                purpose: params.purpose,
+                depth: params.depth ?? "standard",
+            }, {
+                search: (query, maxResults) => searchWeb(query, maxResults, searchOptions),
+            });
+            const reportDir = join(projectRoot, ".inkos", "research");
+            await mkdir(reportDir, { recursive: true });
+            const fileName = `${new Date().toISOString().replace(/[:.]/g, "-")}-${slugResearchTopic(params.topic)}.md`;
+            const reportPath = join(reportDir, fileName);
+            await writeFile(reportPath, report.markdown, "utf-8");
+            return textResult([
+                `Research report saved: ${reportPath}`,
+                `Sources: ${report.sources.length}; confidence: ${report.confidence}.`,
+                report.partialFailures.length > 0 ? `Partial failures: ${report.partialFailures.length}.` : "Partial failures: none.",
+            ].join("\n"), {
+                kind: "research_report",
+                reportPath,
+                topic: params.topic,
+                purpose: params.purpose,
+                depth: params.depth ?? "standard",
+                sources: report.sources,
+                claims: report.claims,
+                confidence: report.confidence,
+                partialFailures: report.partialFailures,
+            });
+        },
+    };
+}
+function slugResearchTopic(topic) {
+    const slug = topic
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return slug || "research";
+}
+async function readResearchSearchConfig(projectRoot) {
+    try {
+        const raw = JSON.parse(await readFile(join(projectRoot, "inkos.json"), "utf-8"));
+        return ResearchSearchConfigSchema.parse(raw.researchSearch ?? {});
+    }
+    catch {
+        return ResearchSearchConfigSchema.parse({});
+    }
+}
+// ---------------------------------------------------------------------------
+// 3. Standalone Short Fiction Tool
 // ---------------------------------------------------------------------------
 const ShortFictionRunParams = Type.Object({
     direction: Type.String({
@@ -721,7 +918,241 @@ function summarizeCoverGenerationError(error) {
     return text.slice(0, 300);
 }
 // ---------------------------------------------------------------------------
-// 3. Standalone Cover Tool
+// 3. Script and Storyboard tools
+// ---------------------------------------------------------------------------
+const ScriptCreateParams = Type.Object({
+    title: Type.String({
+        description: "Required script project title.",
+    }),
+    instruction: Type.String({
+        description: "Confirmed script creation instruction, including format, source, and user preferences.",
+    }),
+    sourceKind: Type.Optional(Type.String({
+        description: "Source type, e.g. novel excerpt, original idea, outline, existing script.",
+    })),
+    targetFormat: Type.Optional(Type.Union([
+        Type.Literal("vertical_short_drama"),
+        Type.Literal("screenplay"),
+        Type.Literal("audio_drama"),
+        Type.Literal("interactive_script"),
+        Type.Literal("general_script"),
+    ], { description: "Confirmed script output format." })),
+    sourceText: Type.Optional(Type.String({
+        description: "User-provided source text. For long sources, prefer sourcePath instead of summarizing.",
+    })),
+    sourcePath: Type.Optional(Type.String({
+        description: "Optional project-relative source file path.",
+    })),
+    requirements: Type.Optional(Type.String({
+        description: "Confirmed script format, production constraints, tone, episode structure, or user preferences.",
+    })),
+    episodeCount: Type.Optional(Type.Number({
+        description: "Optional target episode/segment count.",
+    })),
+    episodeDuration: Type.Optional(Type.String({
+        description: "Optional per-episode/per-segment duration.",
+    })),
+    projectId: Type.Optional(Type.String({
+        description: "Optional output id under dramas/.",
+    })),
+    outDir: Type.Optional(Type.String({
+        description: "Optional project-relative output directory. Default dramas/.",
+    })),
+});
+export function createScriptCreationTool(pipeline, projectRoot, options = {}) {
+    return {
+        name: "script_create",
+        description: "Create a script project from a novel excerpt, idea, outline, or existing script. " +
+            "Writes human-readable Markdown spec and script files under dramas/.",
+        label: "Script Creation",
+        parameters: ScriptCreateParams,
+        async execute(_toolCallId, params, _signal, onUpdate) {
+            const progress = (message) => onUpdate?.(textResult(message));
+            const payload = options.actionPayload?.scriptCreate;
+            const result = await runScriptCreation({
+                projectRoot,
+                runtime: pipeline.createAgentContext("script-creation"),
+                title: payload?.title ?? params.title,
+                instruction: params.instruction,
+                sourceKind: payload?.sourceKind ?? params.sourceKind,
+                targetFormat: (payload?.targetFormat ?? params.targetFormat),
+                sourceText: payload?.sourceText ?? params.sourceText,
+                sourcePath: payload?.sourcePath ?? params.sourcePath,
+                requirements: payload?.requirements ?? params.requirements,
+                episodeCount: payload?.episodeCount ?? params.episodeCount,
+                episodeDuration: payload?.episodeDuration ?? params.episodeDuration,
+                projectId: payload?.projectId ?? params.projectId,
+                outDir: payload?.outDir ?? params.outDir,
+                onProgress: progress,
+            });
+            return textResult([
+                `Script "${result.projectId}" completed.`,
+                `Spec: ${result.specPath}`,
+                `Script: ${result.scriptPath}`,
+            ].join("\n"), { kind: "script_created", ...result });
+        },
+    };
+}
+const StoryboardCreateParams = Type.Object({
+    title: Type.String({
+        description: "Required storyboard project title.",
+    }),
+    instruction: Type.String({
+        description: "Confirmed storyboard creation instruction, including source, style, aspect ratio, and shot granularity.",
+    }),
+    sourceKind: Type.Optional(Type.String({
+        description: "Source type, e.g. script, novel excerpt, idea, scene list.",
+    })),
+    sourceText: Type.Optional(Type.String({
+        description: "User-provided source text. For long sources, prefer sourcePath instead of summarizing.",
+    })),
+    sourcePath: Type.Optional(Type.String({
+        description: "Optional project-relative source file path.",
+    })),
+    requirements: Type.Optional(Type.String({
+        description: "Confirmed shot/storyboard requirements.",
+    })),
+    visualStyle: Type.Optional(Type.String({
+        description: "Confirmed visual style, if the user specified one.",
+    })),
+    aspectRatio: Type.Optional(Type.String({
+        description: "Confirmed aspect ratio, e.g. 9:16, 16:9, 1:1.",
+    })),
+    granularity: Type.Optional(Type.String({
+        description: "Confirmed storyboard granularity.",
+    })),
+    maxShots: Type.Optional(Type.Number({
+        description: "Optional max shot count.",
+    })),
+    projectId: Type.Optional(Type.String({
+        description: "Optional output id under storyboards/.",
+    })),
+    outDir: Type.Optional(Type.String({
+        description: "Optional project-relative output directory. Default storyboards/.",
+    })),
+});
+export function createStoryboardCreationTool(pipeline, projectRoot, options = {}) {
+    return {
+        name: "storyboard_create",
+        description: "Create a storyboard project and image prompts from a script, novel excerpt, idea, or scene list. " +
+            "Writes human-readable Markdown spec, storyboard, and image prompt files under storyboards/.",
+        label: "Storyboard Creation",
+        parameters: StoryboardCreateParams,
+        async execute(_toolCallId, params, _signal, onUpdate) {
+            const progress = (message) => onUpdate?.(textResult(message));
+            const payload = options.actionPayload?.storyboardCreate;
+            const result = await runStoryboardCreation({
+                projectRoot,
+                runtime: pipeline.createAgentContext("storyboard-creation"),
+                title: payload?.title ?? params.title,
+                instruction: params.instruction,
+                sourceKind: payload?.sourceKind ?? params.sourceKind,
+                sourceText: payload?.sourceText ?? params.sourceText,
+                sourcePath: payload?.sourcePath ?? params.sourcePath,
+                requirements: payload?.requirements ?? params.requirements,
+                visualStyle: payload?.visualStyle ?? params.visualStyle,
+                aspectRatio: payload?.aspectRatio ?? params.aspectRatio,
+                granularity: payload?.granularity ?? params.granularity,
+                maxShots: payload?.maxShots ?? params.maxShots,
+                projectId: payload?.projectId ?? params.projectId,
+                outDir: payload?.outDir ?? params.outDir,
+                onProgress: progress,
+            });
+            return textResult([
+                `Storyboard "${result.projectId}" completed.`,
+                `Spec: ${result.specPath}`,
+                `Storyboard: ${result.storyboardPath}`,
+                `Image prompts: ${result.imagePromptsPath}`,
+                `Image assets: ${result.assetsManifestPath}`,
+            ].join("\n"), { kind: "storyboard_created", ...result });
+        },
+    };
+}
+const InteractiveFilmCreateParams = Type.Object({
+    title: Type.String({
+        description: "Required interactive-film project title.",
+    }),
+    instruction: Type.String({
+        description: "Confirmed interactive-film creation instruction, including branching, variables/flags, endings, source, and user preferences.",
+    }),
+    sourceKind: Type.Optional(Type.String({
+        description: "Source type, e.g. novel excerpt, script, outline, original idea.",
+    })),
+    sourceText: Type.Optional(Type.String({
+        description: "User-provided source text. For long sources, prefer sourcePath instead of summarizing.",
+    })),
+    sourcePath: Type.Optional(Type.String({
+        description: "Optional project-relative source file path.",
+    })),
+    requirements: Type.Optional(Type.String({
+        description: "Confirmed branching, variable/flag, ending, production, visual, or market requirements.",
+    })),
+    targetAudience: Type.Optional(Type.String({
+        description: "Optional confirmed target audience or market.",
+    })),
+    episodeCount: Type.Optional(Type.Number({
+        description: "Optional target episode/segment count.",
+    })),
+    episodeDuration: Type.Optional(Type.String({
+        description: "Optional per-episode/per-segment duration.",
+    })),
+    budget: Type.Optional(Type.String({
+        description: "Optional budget or production constraints.",
+    })),
+    referenceMode: Type.Optional(Type.String({
+        description: "Optional reference mode, e.g. 盛世天下-style multi-ending interactive drama.",
+    })),
+    projectId: Type.Optional(Type.String({
+        description: "Optional output id under interactive-films/.",
+    })),
+    outDir: Type.Optional(Type.String({
+        description: "Optional project-relative output directory. Default interactive-films/.",
+    })),
+});
+export function createInteractiveFilmCreationTool(pipeline, projectRoot, options = {}) {
+    return {
+        name: "interactive_film_create",
+        description: "Create an interactive film/game script package with story tree, variables/flags, endings, script, storyboard, and image prompts. " +
+            "Writes human-readable Markdown files under interactive-films/.",
+        label: "Interactive Film Creation",
+        parameters: InteractiveFilmCreateParams,
+        async execute(_toolCallId, params, _signal, onUpdate) {
+            const progress = (message) => onUpdate?.(textResult(message));
+            const payload = options.actionPayload?.interactiveFilmCreate;
+            const result = await runInteractiveFilmCreation({
+                projectRoot,
+                runtime: pipeline.createAgentContext("interactive-film-creation"),
+                title: payload?.title ?? params.title,
+                instruction: params.instruction,
+                sourceKind: payload?.sourceKind ?? params.sourceKind,
+                sourceText: payload?.sourceText ?? params.sourceText,
+                sourcePath: payload?.sourcePath ?? params.sourcePath,
+                requirements: payload?.requirements ?? params.requirements,
+                targetAudience: payload?.targetAudience ?? params.targetAudience,
+                episodeCount: payload?.episodeCount ?? params.episodeCount,
+                episodeDuration: payload?.episodeDuration ?? params.episodeDuration,
+                budget: payload?.budget ?? params.budget,
+                referenceMode: payload?.referenceMode ?? params.referenceMode,
+                projectId: payload?.projectId ?? params.projectId,
+                outDir: payload?.outDir ?? params.outDir,
+                onProgress: progress,
+            });
+            return textResult([
+                `Interactive film "${result.projectId}" completed.`,
+                `Spec: ${result.specPath}`,
+                `Story graph: ${result.storyGraphPath}`,
+                `Story tree: ${result.storyTreePath}`,
+                `Flags: ${result.flagsPath}`,
+                `Script: ${result.scriptPath}`,
+                `Storyboard: ${result.storyboardPath}`,
+                `Image prompts: ${result.imagePromptsPath}`,
+                `Image assets: ${result.assetsManifestPath}`,
+            ].join("\n"), { kind: "interactive_film_created", ...result });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 4. Standalone Cover Tool
 // ---------------------------------------------------------------------------
 const GenerateCoverParams = Type.Object({
     title: Type.String({