Skip to content

Narrative Agent Split Implementation Log

Created: 2026-05-29 07:32 UTC

Date/time started: 2026-05-29 09:10 UTC

Date/time completed: 2026-05-29 12:35 UTC

Status

Implementation completed. Code, docs, and targeted verification were updated for the split between preview-only narrative generation and post-approval scene-detail expansion.

Delivery Flow

flowchart TD
  contracts["Split contracts and agent definitions"] --> preview["Preview workflow emits VoiceoverScriptJson"]
  preview --> review["narrative-review persists approvedScript only"]
  review --> expand["Expansion workflow emits NarrativeSceneDetails"]
  expand --> downstream["Visuals, slides, direction, compile consume expanded scenes"]
  downstream --> verify["Typecheck and targeted tests"]
  verify --> docs["Core/state docs and implementation log updated"]

Completed Tasks

  • Added explicit preview and expansion narrative contracts, with compatibility helpers for legacy narrativeScenes
  • Split the narrative agent into preview-generation and scene-expansion actions
  • Refactored the narrative subworkflow into preview generation plus post-approval expansion
  • Reworked the master presentation workflow around a preview-only narrative-review suspend boundary
  • Added deterministic skip gating for IntentAgent and KnowledgeOrchestrator
  • Narrowed persisted review state and resume payloads to approved-script review semantics
  • Retargeted visuals, slides, direction, compiler, and scene persistence to expanded-scene ownership
  • Updated action-layer parsing and preview/resume UI flow to use approvedScript
  • Updated core and state docs to match the new workflow
  • Ran targeted verification and recorded remaining risks

Files Changed

  • src/lib/anuva/contracts-v1.ts
  • src/lib/anuva/voiceover-script.ts
  • src/lib/anuva/orchestration-service.ts
  • src/mastra/schemas/scene.schema.ts
  • src/mastra/agents/presentationvideo-agent-contracts.ts
  • src/mastra/agents/narrative.agent.ts
  • src/mastra/runtime.ts
  • src/mastra/workflows/sub/narrative.workflow.ts
  • 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/mastra/workflows/presentationvideo.workflow.ts
  • src/mastra/tools/compiler/index.ts
  • src/mastra/tools/presentation/index.ts
  • src/app/(frontend)/app/presentation/actions.ts
  • src/components/anuvax/presentation-video/presentation-video-page.tsx
  • tests/unit/anuva-contracts.test.ts
  • tests/integration/helpers/mock-runtime.ts
  • tests/integration/presentation-compile.integration.test.ts
  • docs/core/PresentationVideoWorkflow.md
  • docs/state/WorkflowMap.md
  • docs/state/ServerActionsMap.md
  • docs/changes/2026-05-29-0732-narrative-agent-split/ImplementationPlan.md
  • docs/changes/2026-05-29-0732-narrative-agent-split/ImplementationLog.md

Code Changes

  • VoiceoverScriptJson remains the preview and approved-script contract
  • Added NarrativeSceneDetails as the post-approval semantic-expansion contract
  • presentationVideoAgentDefinitions now exposes narrativePreview and narrativeExpansion
  • narrative.workflow.ts now separates preview generation from expansion and forces approved preview text to remain the hard input during expansion
  • presentationvideo.workflow.ts now:
  • derives skipIntentAgent from explicit normalized input
  • derives skipKnowledgePlanning from uploaded-only sources
  • suspends at narrative-review with voiceoverPreview and approvedScript
  • resumes into expansion using approval plus identity inputs only
  • visualsWorkflow now owns recommendedVisualType and visualGenerationPrompt
  • Slide and direction flows now consume expanded narrative scene details instead of mixed preview/semantic narrative output
  • Workflow-scene persistence now stores narrative-owned semantic fields from expansion and visual-owned fields from visuals

Docs Changes

  • Updated docs/core/PresentationVideoWorkflow.md to document the preview-first, expansion-after-approval architecture
  • Updated docs/state/WorkflowMap.md to reflect the new workflow boundaries and skip gates
  • Updated docs/state/ServerActionsMap.md to reflect approvedScript preview responses and narrowed resume input
  • Reviewed docs/state/KnownGaps.md; no new shared-system gap required documentation for this change

Verification

Commands run:

  • pnpm typecheck — passed
  • pnpm exec vitest run --config ./vitest.config.mts tests/integration/presentation-compile.integration.test.ts tests/unit/anuva-contracts.test.ts — passed
  • pnpm exec biome check 'src/app/(frontend)/app/presentation/actions.ts' 'src/mastra/workflows/sub/rag.workflow.ts' 'src/mastra/workflows/presentationvideo.workflow.ts' 'src/mastra/workflows/sub/narrative.workflow.ts' 'docs/changes/2026-05-29-0732-narrative-agent-split/ImplementationPlan.md' 'docs/changes/2026-05-29-0732-narrative-agent-split/ImplementationLog.md' — passed after formatting/import cleanup
  • pnpm lint — failed on pre-existing repo-wide issues in untouched files including docs/web/stylesheets.css, docs/_stale/archive/globals.css, and src/payload-types.ts

Verification focus:

  • Preview responses now suspend with approvedScript rather than semantic narrativeScenes
  • Resume path no longer accepts edited preview scenes
  • Expansion preserves approved preview text while adding caption, sceneQuery, and voScriptSection
  • Visual ownership moved to visualsWorkflow for recommendedVisualType and visualGenerationPrompt
  • Downstream compile paths still pass targeted integration coverage

Deviations From Plan

  • docs/state/KnownGaps.md was reviewed but not edited because the change did not introduce a new persistent architectural gap beyond the scoped remaining risks captured here
  • narrativeSceneListSchema was retained as a compatibility alias to reduce churn while converting downstream consumers incrementally

Remaining Risks

  • Legacy suspended runs that persisted unusually malformed narrativeScenes may still fail compatibility conversion if required preview fields are missing or invalid
  • Skip gating is deterministic but currently tied to normalized request/source shape; if future callers send ambiguous partial input, they may still invoke IntentAgent or knowledge planning more often than desired
  • Visual ownership is cleaner now, but prompt quality across preview and expansion should still be watched for semantic drift in real user runs
  • Full-repo lint remains noisy because of unrelated existing issues outside the touched surface, so pnpm lint is not yet a clean release gate for this change in isolation