Skip to content

Narrative Agent Split Implementation Plan

Created: 2026-05-29 07:32 UTC

Goal

Refactor the presentation-video narrative stage so narrative-review becomes a true human approval boundary over previewable voiceover text only. The workflow should generate a narrow approved script first, then resume into a separate semantic-expansion phase before visuals, slides, direction, compile, and optional audio.

Non-goals

  • Add sentence-level editing inside the preview approval UI
  • Redesign Step 3 scene editing or final audio/render flows
  • Introduce Payload collection migrations unless implementation proves one is unavoidable
  • Change public create-flow behavior for older compatibility callers beyond adapting them to the new internal contracts

Current Behavior

  • presentationVideoWorkflow always runs IntentAgent, then ragWorkflow, then one narrativeWorkflow
  • narrativeWorkflow returns NarrativeSceneList, which mixes preview fields with downstream semantic fields
  • narrative-review suspends on a payload containing voiceoverPreview plus full narrativeScenes
  • continuePresentationFromNarrative can resume with narrativeScenes
  • visualsWorkflow, slidesWorkflow, directionWorkflow, and compile all assume narrative has already produced semantic scene details

Target Behavior

  • Preview mode skips IntentAgent when normalized videoName, description, and voScriptDescription are all present and non-empty
  • Preview mode skips KnowledgeOrchestrator when normalized sources are uploaded-only
  • Preview generation outputs a voiceover-only contract using VoiceoverScriptJson
  • narrative-review persists and suspends on the approved-preview artifact, not on full semantic scene details
  • Resume accepts only approval plus identity selections; it does not accept user-edited preview sentences
  • Post-approval expansion outputs a new NarrativeSceneDetails artifact containing approved voiceover text plus narrative-owned semantic fields
  • caption and voScriptSection are expansion-owned
  • sceneQuery is expansion-owned
  • recommendedVisualType and visualGenerationPrompt move to visualsWorkflow
  • reveal or slide hints remain slidesWorkflow-owned
  • Downstream workflows consume the expanded artifact, not the preview artifact

Planned Flow

flowchart TD
  prepare["prepareRunStep"] --> intentGate{"Stable name + description + VO guidance?"}
  intentGate -->|Yes| ragGate
  intentGate -->|No| intent["IntentAgent"]
  intent --> ragGate

  ragGate{"Uploaded-only sources?"} -->|Yes| retrieve["Retrieve persisted/uploaded RAG context"]
  ragGate -->|No| knowledge["KnowledgeOrchestrator + ragWorkflow"]

  retrieve --> preview["generatePreviewSentences"]
  knowledge --> preview
  preview --> normalize["Normalize approved preview script"]
  normalize --> suspend["narrative-review suspend with VoiceoverScriptJson"]
  suspend --> approve["User approval + identity selection"]
  approve --> expand["expandSceneDetails -> NarrativeSceneDetails"]
  expand --> visuals["visualsWorkflow"]
  visuals --> slides["slidesWorkflow"]
  slides --> direction["directionWorkflow"]
  direction --> compile["compile"]
  compile --> persist["persist scenes + compilation + optional audio/finalize"]

Important Contract Changes

  • Keep VoiceoverScriptJson as the preview and approved-script persistence contract
  • Add NarrativeSceneDetails as the post-approval expansion contract
  • Replace workflow suspend/resume usage of narrativeScenes with:
  • suspend payload: voiceoverPreview plus approvedScript
  • resume payload: approved, setVariantId, botVariantId, optional brandKitId
  • Preserve external compile result shape and Step 3 scene UI shape

Affected Files And Modules

Workflow and agent surface

  • src/mastra/agents/presentationvideo-agent-contracts.ts
  • src/mastra/agents/narrative.agent.ts
  • src/mastra/workflows/sub/narrative.workflow.ts
  • src/mastra/workflows/presentationvideo.workflow.ts

Schema and helper surface

  • src/mastra/schemas/scene.schema.ts
  • src/mastra/schemas/config.schema.ts
  • src/lib/anuva/contracts-v1.ts
  • src/lib/anuva/voiceover-script.ts
  • src/mastra/tools/compiler/index.ts
  • src/mastra/tools/presentation/index.ts

Downstream consumers and compatibility paths

  • src/mastra/workflows/sub/rag.workflow.ts
  • src/mastra/workflows/sub/visuals.workflow.ts
  • src/mastra/workflows/sub/slides.workflow.ts
  • src/mastra/workflows/sub/direction.workflow.ts
  • src/app/(frontend)/app/presentation/actions.ts

Affected Docs

  • docs/core/PresentationVideoWorkflow.md
  • docs/state/WorkflowMap.md
  • docs/state/ServerActionsMap.md
  • docs/state/KnownGaps.md
  • docs/changes/2026-05-29-0732-narrative-agent-split/ImplementationLog.md

Data And Schema Impact

  • No Payload collection schema migration is planned
  • presentationStatusJson.setup.narrativeReview changes shape going forward to store approved preview script instead of full narrativeScenes
  • Add compatibility reads for legacy persisted review payloads containing narrativeScenes; derive approvedScript from legacy data when resuming or reading old suspended state
  • Mastra workflow schemas, helper types, and parse/format utilities will change, but compiled public config contracts remain stable

Implementation Phases

Phase 1. Define contracts and compatibility helpers

  • Add NarrativeSceneDetails and related scene-detail types in the Mastra schema layer
  • Keep VoiceoverScriptJson as the preview artifact and add helper functions to:
  • derive plain-text preview from VoiceoverScriptJson
  • derive legacy-compatible preview script from old NarrativeSceneList if needed
  • Update contract exports and parsing helpers so preview and expansion artifacts are distinct and explicitly named

Phase 2. Split the narrative agent and subworkflow

  • Replace agent.narrative.generateScenes with:
  • agent.narrative.generatePreviewSentences
  • agent.narrative.expandSceneDetails
  • Update preview instructions so they are restricted to ordered voiceover-only scenes
  • Update expansion instructions so approved sentences are hard inputs and must not be re-authored
  • Refactor narrative.workflow.ts into preview generation, preview normalization, and expansion generation

Phase 3. Rework master workflow branching and review state

  • Add deterministic gating in prepareRunStep or equivalent normalized input:
  • skipIntentAgent when normalized name, prompt, and voScriptDescription are all non-empty
  • skipKnowledgePlanning when all normalized sources are uploaded
  • Branch the master workflow so preview mode can bypass IntentAgent and/or KnowledgeOrchestrator without caller-supplied flags
  • Suspend at narrative-review with voiceoverPreview and approvedScript
  • Resume with approval plus identity only, then run expansion and downstream subworkflows
  • Change persistNarrativeReviewTool to write the new review payload shape

Phase 4. Retarget downstream consumers

  • Update action-layer result types and parsers in presentation/actions.ts:
  • generatePresentationNarrativePreview returns approvedScript instead of narrativeScenes
  • continuePresentationFromNarrative no longer accepts edited narrativeScenes
  • Adapt compatibility workflow-backed generation paths so they still auto-approve internally against the new preview/resume contracts
  • Update visualsWorkflow input to consume NarrativeSceneDetails and generate:
  • recommendedVisualType
  • visualGenerationPrompt
  • visualIntent
  • Update slidesWorkflow and helper tools to consume expanded scenes for:
  • caption
  • voScriptSection
  • approved scene text
  • Update direction and compiler helpers to depend only on fields still owned by their upstream artifacts

Phase 5. Tests and docs parity

  • Add unit coverage for:
  • preview normalization
  • legacy narrativeScenes to approvedScript compatibility conversion
  • expansion preserving approved text exactly
  • Add workflow/integration coverage for:
  • preview path with explicit inputs skipping IntentAgent
  • uploaded-only source path skipping KnowledgeOrchestrator
  • suspend payload containing preview-only data
  • resume path using approval plus identity only
  • compatibility caller auto-approve path still succeeding
  • Update core/state docs to describe the new two-stage narrative architecture and skip rules

Tasks

  • [x] 1. Add NarrativeSceneDetails schema and preview/compatibility helpers
  • [x] 2. Split narrative agent definitions into preview and expansion actions
  • [x] 3. Refactor narrative.workflow.ts into preview, normalize, and expand phases
  • [x] 4. Add deterministic skip gating for intent and knowledge planning in the master workflow
  • [x] 5. Narrow narrative-review suspend/resume payloads and persisted review state
  • [x] 6. Update action-layer preview/resume parsing and compatibility workflow callers
  • [x] 7. Retarget visuals/slides/direction/compiler consumers to expanded-scene ownership
  • [x] 8. Add or update tests for preview, resume, compatibility, and downstream compile behavior
  • [x] 9. Update docs and record implementation details in ImplementationLog.md
  • [x] 10. Run verification

Verification Plan

  • Run pnpm lint
  • Run pnpm typecheck
  • Run targeted tests covering narrative preview/resume behavior and downstream workflow compilation
  • Run pnpm test:int because this changes presentation actions and workflow orchestration
  • Verify:
  • preview result contains VoiceoverScriptJson-backed approved script and not full semantic scenes
  • post-approval expansion produces caption, sceneQuery, and voScriptSection
  • visualsWorkflow now owns recommendedVisualType and visualGenerationPrompt
  • compile result remains valid for downstream consumers
  • legacy persisted review payloads continue to load/resume successfully

Docs Parity Checklist

  • [x] Update docs/core/PresentationVideoWorkflow.md to show the split between preview generation and semantic expansion
  • [x] Update docs/state/WorkflowMap.md to reflect new subworkflow boundaries and skip gates
  • [x] Update docs/state/ServerActionsMap.md to reflect preview return-shape and resume-input changes
  • [x] Review docs/state/KnownGaps.md; no update required because no new tracked gap or limitation was introduced beyond the change-specific log
  • [x] Update docs/changes/2026-05-29-0732-narrative-agent-split/ImplementationLog.md with actual files changed, commands run, and deviations from plan

Acceptance Criteria

  • Generate VO Script Preview produces a preview-only approved-script artifact and suspends at narrative-review
  • narrative-review no longer persists full semantic narrativeScenes for newly written workflow state
  • Preview mode skips IntentAgent when normalized name, prompt, and voScriptDescription are all present and non-empty
  • Preview mode skips KnowledgeOrchestrator when normalized sources are uploaded-only
  • Go To Scene Details resumes with approval plus identity only and runs semantic expansion after the review boundary
  • NarrativeSceneDetails owns caption, sceneQuery, and voScriptSection
  • visualsWorkflow owns recommendedVisualType and visualGenerationPrompt
  • Slide/reveal hints remain slide-owned, not narrative-owned
  • Existing compile/public-config outputs remain valid without Payload schema migration
  • Compatibility workflow callers that auto-approve the review boundary still succeed without changing their external behavior

Assumptions

  • Preview review remains approve/regenerate-only for this change
  • No sentence-level editing is introduced at the review boundary
  • Caller-supplied flags are not used to control skip behavior; skip decisions are derived inside workflow normalization
  • Legacy persisted narrativeScenes review state is read compatibly, but all new writes use the new review payload shape
  • The implementation should minimize public action shape churn beyond replacing preview/resume narrativeScenes usage with approvedScript